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The disk I/O routines explained in this section allow disk files to be read from and written to 
during Run mode. “Streams” describes how most of the routines operate on a data stream 
rather than the actual file. Under "Routines,” all the disk I/O routines are explained. These 
routines perform read and write functions as well as other file maintenance tasks in Run 
mode, such as creating directories, renaming files, and deleting files. 

68.1 Streams 

Most disk I/O routines are not executed on the actual disk file, but on a stream 
which includes a copy of the file’s data. Opening a disk file for reading or writing 
associates a stream with the file. A stream may be input or output. Input streams 
are read-only. Output streams are write-only. In either case, the stream remains 
associated with a disk file until the file is closed. 

You may have more than one stream associated with a given file. (A maximum of 
ten streams may be open at one time.) For example, to read from and write to an 
existing file, you must open the file twice, once to create an input stream and once 
to create an output stream. 

(A) Stream Components 

A stream contains everything needed to perform disk I/O functions on a file. 

1. Buffer. A buffer containing a copy of the data in a disk file is part of the 
stream. When a disk file is opened for reading, sectors of the disk 
containing the file are copied to this buffer. 

Sometimes a file’s size may exceed the maximum size (512 bytes) of the 
buffer. In this instance, as much data from the file as will fit in the buffer is 
copied. As each character is read from the input stream, it is removed. 

(The ungetc routine may temporarily return a removed character to an input 
stream.) Each call to fread, fgetc, or fgels further empties the buffer, while 
leaving the contents of the disk file unchanged. When the buffer is empty, 
the next sector (or sectors) of the disk file is (are) automatically copied into 
the buffer. 

Similarly, when a file is opened for writing, the empty buffer is filled as 
fwrite or other output routines are invoked. Characters written to the output 
stream are not transferred to the disk file until there is a call to fflush. 

Fflush is automatic in fclose or when the stream buffer is full. 
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2. File-position indicator. The file-position indicator keeps track of 
progression through the disk file. For files opened in read mode, the 
indicator is initially located at the first character (character zero) in the file. 
As characters are read from the input stream, the indicator advances through 
the file. 

For existing files opened in append mode, the indicator is positioned after 
the last character in the file. For newly created files or files opened in 
overwrite mode, it is located at the beginning of the file. Every time an 
output routine is executed, the file-position indicator is advanced by the 
number of characters successfully written to the stream. 

3. Buffer pointer. The stream also contains a pointer into the associated buffer 
of a file. In input streams, it points to the next character to be read. In 
output streams, it points to the next empty byte. 

4. EOF indicator. If the end-of-file (EOF) indicator is set in a input stream, 
it means that a read operation encountered the end of the file. The EOF 
indicator is cleared via calls to fopen, fseek, rewind, clearerr, or ungetc. 

5. Error indicator. In input streams, this indicator gets set when an fread, 
fgetc, o t fgets routine does not successfully execute. Attempting to execute 
these input routines (or ungetc) on an output stream sets the error indicator. 
In output streams, the error indicator gets set when the fflush, fwrite, fputc, 
fputs, or fprintf routine does not successfully execute, or when output 
routines try to execute on an input stream. A call to fopen, clearerr, or 
fseek, clears the error indicator in either input or output streams. A rewind 
operation on an input stream also clears the indicator. 

(B) Stream Pointer 

The fopen routine returns a pointer to the stream. Disk I/O routines which 
perform operations on a stream require the stream pointer as an argument. It 
has been named stream _ptr in the routines discussed below. 

(C) Locking Streams 

Each file stream is locked internally during operations on it. If the user program 
is executing different conditions on multiple processors and both actions require 
writing to the same file stream, internally the stdio library will allow the first task 
that requests to write to execute until completion and the second task will be 
locked out. All processes that are locked out are temporarily put to sleep and 
removed from the tasking queues for that CPU. When the first process 
completes its operations on the stream, the locked-out processes are woken up 
and may try to claim the lock. Deadlock or deadly embrace situations can 
never arise internally to the stdio library. 
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If two or more file streams are associated with a single file, processes on each 
stream may try to operate on the file concurrently. Internal locking does not 
apply in this situation, so use the locking routines. 

68.2 Routines 

Disk I/O routines fall into four categories. The first category includes routines valid 
for both input and output streams, including the two locking routines (not exclusive 
to disk I/O). The remaining groups are routines valid for input streams only, routines 
applicable to output streams only, and routines which handle other file maintenance 
functions. 

The routines and their descriptions closely conform to the ANSI specification for the 
Programming Language C, as defined in the draft document published July 9, 1986. 
Discrepancies with the ANSI standard are noted. The document number is 
X3J11-86-098. Refer to pages 107-129. 

Use the # include <stdio.h> preprocessor directive with all disk I/O routines. The 
stdio.h fife contains type definitions and function prototypes, making declarations of 
the routines unnecessary. 

When a filename is required as an argument, give the absolute pathname of the file, 
prefixed by the device name. Valid device names are FD1, FD2, or HRD. See 
Section 14.2(B) for a discussion of absolute pathnames. The disk filename is 
required as an argument for the fopen routine, which opens a file for reading or 
writing. From that point on, disk I/O routines relating to that file use the stream 
pointer, explained above, as input. File maintenance routines, such as rename or 
remove, use the filename as input. 

NOTE: A single program can perform disk I/O functions as well 
as data playback or recording. Disk I/O, however, must be 
suspended while disk recording (or playback) proceeds, and vice 
versa. RAM recording, on the other hand, may occur 
simultaneously with disk I/O operations. Refer to the 
start_rcrd _play and suspend_rcrd _play routines in Section 72 for 
more information on the interaction between disk I/O and 
recording/playback. 

(A) Input/Output-Stream Routines 

Several disk I/O routines may be executed on either input or output streams. 
fopen opens an existing disk file for reading or writing, or creates a new file. In 
each case, a stream is associated with the file until there is a call to fclose. 
fclose or a specific call to fflush delivers any output written to a stream to the 
host environment where it will be written to the disk file. 

NOTE: Always include a call to fclose in your program to make 
sure output is written to the file. 
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Test the end-of-file and error indicators with the feof and fervor routines, 
respectively. These same indicators may be cleared via the clearer r routine. 

The / seek and rewind routines manipulate the file-position indicator and erase 
any memory of a character put into the stream via ungetc. 

The lock and unlock routines prevent deadlock from occurring when processes 
on multiple streams try to operate concurrently on a single file. 


fopen 

Synopsis 

tt Include <stdio.h> 

extern FILE * fopen (filename _ptr, mode _plr); 
const char * filename __ptr; 
const char * mode _ptr; 

Description 

The fopen routine opens a file for access. Depending on the open mode, a file 
can be opened for reading (via an input stream) or for writing (via an output 
stream). For existing files, this routine also clears the end-of-file and error ( 

indicators. 

Inputs 

The first parameter is a pointer to the file to be opened, represented as the 
name of the file, placed inside double quotation marks. The filename must be 
the absolute pathname, prefixed by the device name (HRD, FD1, or FD2). 

The second parameter is a pointer to a string (represented as a character inside 
double quotation marks) which identifies the type of open to be performed. Of 
the ANSI standard open modes, the following are supported: 

r Open an existing file for reading only. The file-position indicator is 

located at the start (character zero) of the file. 

w Create a file, or open an existing file, for writing only. For an existing 
file, truncate its length to zero and discard the contents. 

a Create a file, or open an existing file, for writing only. For an existing 

file, retain the contents and locate the file-position indicator at the 
end of the file. Append new data to the end of existing data, unless 
a call to fseek or rewind has repositioned the file-position indicator. 

In this instance, overwrite existing data. (This implementation is 
different from the ANSI specification which appends new data to the 
end of existing data regardless of any previous calls to fseek.) ( 
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rb Currently implemented the same as “r.” Use ‘‘rb" for the /seek 
routine. 

wb Currently implemented the same as “w." Use “wb” for the fseek 
routine. 

ab Currently implemented the same as "a." Use “ab” for the fseek 
routine. 

Returns 

This routine returns a pointer to the stream, with a type definition FILE 
(defined in the stdio.h file). 

If the open fails (for example, the file does not exist), zero is returned. 

Example 

Open a file called " buffO 1" in the /usr directory on a disk in floppy drive 2. 
Store the pointer to the stream in stream _ptr. Indicate whether or not the open 
is successful on the prompt line. 

{ 

it Include <stdio.h> 

FILE * stream _ptr; 

} 

LAYER: 1 

STATE: open_a_flle 

CONDITIONS: ENTER_STATE 
ACTIONS: PROMPT 'Press O to open file. 

CONDITIONS: KEYBOARD “oO” 

ACTIONS: 

{ 

If ((stream _plr = fopen("FD2lusrlbuff01” , ”r")) == 0) 
display _prompt(“ Cannot open file. 
else 

display _prompt(“Fi!e opened. "); 

) 


fclose 

Synopsis 

ttinclude <stdio.h> 

extern int fclose(stream _ptr\; 

FILE * stream _ptr; 

Description 

All opened files must be closed. If the disk file to be closed is an input file, 
then any data remaining in the stream buffer is discarded. If the file is an 
output file, any data written to the stream is written to the file. (In other words, 
fclose automatically calls fflush.) The stream is freed from its association with 
the disk file, and the disk file is closed. 
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Inputs 

The only parameter is the stream pointer. 

Returns 

If the stream is successfully closed, zero is returned. If errors are detected, or if 
the stream is already closed, a non-zero value is returned. 

Example 

Close the file that was opened in the fopen example. Indicate whether or not 
the close is successful on the prompt line. 

{ 

# Include <stdio.h> 

FILE * stream _ptr; 

) 

LAYER: 1 

STATE: open_and_close_a_flle 
CONDITIONS: ENTER_STATE 
ACTIONS: PROMPT “Press O to open file. 

CONDITIONS: KEYBOARD “oO” 

ACTIONS: 

{ 

If ((stream _ptr - fopen('‘FD2/usrlbuff01’\ " r ")) == 0) 

display _prompt ("Cannot open file. "); 

else 

display _prompt(“ File opened. 

I 

CONDITIONS: KEYBOARD “cC“ 

ACTIONS: 

{ 

lf(fdose(stream _ptr) 1= 0) 

display_prompt(“Eilher file is already closed, or close cannot be executed. "); 
else 

dlsplay_prompt("File closed. ”); 

> 


fflush 

Synopsis 

ttinclude <stdio.h> 
extern int fflush(stream _plr ) 

FILE * stream _ptr; 

Description 

If stream _ptr points to an output stream, the fflush routine causes any unwritten 
data for that stream to be delivered to the host environment where it will be 
written to the file. If stream _ptr points to an input stream, the fflush routine 
undoes the effect of any preceding ungetc operation on the stream. 

Inputs 

The only parameter is the stream pointer. { 
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Bs mrn s 

If a write error occurs, non-zero is returned and the error indicator is set. 
Example 

Assume the X.25 personality package has been loaded in at Layer 2. Whenever 
you receive a frame type “unknown,” write the actual value of the control byte 
to an output file stream and to the disk file. 

{ 

itlnclude <stdlo. h> 

FILE * stream _ptr; 

extern volatile const unsigned char rcvd _frame cntrl_byle_I; 

) 

LAYER: 2 

STATE: wrlte_then_fflush 

CONDITIONS: ENTER_STATE 
ACTIONS; 

i/((stream _ptr = fopen("FD2/usr/frame_unkwn", “a")) == 0) 

dlsplay_prompt ("Cannot open file. "); 

else 

display _prorhpt(“ File opened. "); 

pos_cursor(l,0); 

) 

CONDITIONS: RCV UNKNOWN 
ACTIONS: 

< 

if (fprintf (stream _ptr, "%02x\n ", rcvd _frame_cntrl_byte_l) < 0) 

display f(" Error In printing to stream. \n”); 

else 

displayf(“ Print to stream completed. 
if (fflush (stream _ptr) 1= 0) 

disptay_prompl("Write error. ”); 

else 

display_prompt ("Write to file completed. Press C to close file. "); 

} 

CONDITIONS: KEYBOARD “cC’ 

ACTIONS: 

{ 

if(fclose(stream _ptr) /= 0} 

display _prompt (" Either file is already closed, or close cannot be executed. ”); 
else 

dtsplay_prompt("File closed. ”)> 

) 


feof 

Synopsis 

itlnclude <stdio.h> 
extern int feof (stream _ptr); 

FILE ' stream _ptr; 

Description 

This routine tests the end-of-file indicator for an associated stream. 
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Inputs 

The only parameter is the stream pointer. 

Beturns 

The feof routine returns a non-zero value if the end-of-file indicator is set for 
the stream. 

Example 

Get a character from a file. If it is not at the end of the file, display it; 
otherwise prompt with “End of file.” 

< 

ttlnclude <sidlo.h> 

FILE * stream _ptr; 
int character; 

) 

LAYER: 1 

STATE: test for_eof 

CONDITIONS? ENTER_STATE 
ACTIONS; PROMPT “Press O to open file. 

CONDITIONS: KEYBOARD “oO" 

ACTIONS: 

{ 

if ((stream _ptr = fopen(“FD2lusrlbuff01" , “rb ")) == 0) 

display jrompt(“ Cannot open file. ”); 

else 

display j>rompt(“File opened. Press G to get character. “); 

pos cursor (1 ,0); 

} 

CONDITIONS: KEYBOARD “gG" 

ACTIONS: 

{ 

character - fgetc(stream _plr ); 

If (feof (stream _ptr) I = 0) 

display _prompt(" End of file. Press C to close file. "); 

else 

displayf("%c”, character); 

) 

CONDITIONS: KEYBOARD “cC“ 

ACTIONS: 

{ 

if (f close (stream jtr) 1= 0) 

display_prompt (“Either file Is already closed, or close cannot be executed. ") ; 
else 

display _prompt(" File dosed. ”); 

) 


terror 

Synopsis 

ttinclude <stdio.h> 

extern int f error (stream _ptr); 

FILE * stream _ptr; 
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This routine tests the error indicator for a stream. 
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Inputs 

The only parameter is the stream pointer. 


Returns 

The ferror routine returns a non-zero value if the error indicator is set for the 
stream. 


Example 

Read a file called "buf/O I" from the /usr directory on the disk in drive 2, If 
the number of elements read is less than the number designated to be read, 
determine whether an end-of-file was encountered or a read error occurred. 

{ 

# include <stdio.h> 

FILE * stream _ptr; 
char data 16091); 
size t n; 

) 

LAVER: 1 

STATE: read_a_flle 

CONDITIONS: ENTER_STATE 
ACTIONS: PROMPT “Press O to open file. 

CONDITIONS: KEYBOARD “oO" 

ACTIONS: 

{ 

i/((stream __ptr = /open (“FD2I usr/ buffO 1”, “r")) == 0) 

display _prompt(“ Cannot open file. "); 

else 

display _prompt(“ Fite opened. Press R to read the file. "); 

) 

CONDITIONS: KEYBOARD “rR" 

ACTIONS: 

{ 

n = fread(data, 1, 6091, stream _ptr); 
if(n I = 6091) 

if(ferror(stream _ptr ) I = 0) 

display _prompt(" Read error. ")l 

else l/(feof(slream_ptr) /= 0 } 

display _prompt (“End-of-flle encountered. "); 

) 

else 

displayf(“\n%. 6091s", data); 

display _prompt(“ Press C to close the file. ") >' 

} 
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clearerr 

Synopsis 

ttlnrtude <stdio.h> 

extern void clearerr (stream _ptr ); 

FILE * stream _ptr; 


CONDITIONS: KEYBOARD “cC" 

ACTIONS: 

{ 

if(fclose(stream _ptr ) /= 0) 

display _prompt(“ Either file Is already closed, or close cannot be executed, 
else 

display_prompt(“ File closed. 

> 


Description 

This routine clears the end-of-file and error indicators for a stream. When an 
error occurs, no further operations are allowed until the error indicators are 
explicitly cleared. (These indicators are also cleared by a / open or rewind 
operation.) 


IniMS 

The only parameter is the stream pointer. 


Example 

If a write error occurs, clear the indicators. 

{ 

fflnclude <stdlo.h> 

FILE * stream _ptr ; 
int character; 

} 

LAYER: 1 

STATE: clearjndlcatore 

CONDITIONS: ENTER_STAT6 
ACTIONS: PROMPT "Press O to open file. 

CONDITIONS: KEYBOARD “oO" 

ACTIONS: 

{ 

i /((stream _ptr = fopen("FD2lusrlbuff0r , "wb")) == 0) 

display ^prompt (“Cannot open file. ”)< 

else 

display _prompt(" File opened. Press P to write character. "); 

} 
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CONDITIONS: KEYBOARD “pP’ 

ACTIONS; 

< 

character = fputc(‘h’, stream _ptr); 
if (character == EOF) 

{ 

display jsrompt ("Write error. All indicators wilt be cleared. "); 

clearerrfstream _ptr); 

) 

else 

display _prompt(“Wrlte completed. Press C to close the file. ”); 

} 

CONDITIONS: KEYBOARD ~oC” 

ACTIONS: 

< 

if (/close (stream _ptr ) 1= 0) 

dlsplay_prompt(“Elther file Is already closed, or close cannot be executed. ”); 
else 

display j>rompt(“File closed. ”); 

} 


fseek 

Synopsis 

# include <stdio.h> 

extern int fseeK(stream _ptr, bytes, reference); 
FILE * stream _ptr; 
long int bytes; 
int reference; 


Description 

This routine manipulates the file-position indicator, according to the ANSI 
specification for binary files. Future read operations will be referenced from that 
point, fseek clears the end-of-file indicator and resets the ungelc variable. 

NOTE: The ANSI specification for text files is not currently 
implemented. To ensure proper execution of fseek if future 
releases include the ANSI specification for text files, open files 
for fseek as binary (“rb," “wb,” or “ab”). 


Inputs 

The first parameter is the stream pointer. 

The second parameter is the number of characters the file-position indicator 
should be moved from a specified position. A positive number advances the 
file-position indicator forward in the file; a negative number moves it backward. 
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The third parameter specifies the location of the file-position indicator. 
SEEK_SET will move the file-position indicator from the beginning of the file; 
SEEK_END will move the file-position indicator from the end-of-file; and 
SEEK_CUR will move the file-position indicator from its current position. 

Ret urns 

This routine returns non-zero for an improper request; otherwise it returns zero. 


Example 

Open a file and move the file-position indicator 4 characters from the beginning 
of the file. Each time the (D key is pressed, move the indicator one character 
backward from its current position. After 4 executions, the indicator will be 
back at the beginning of the file. 


1 

# include <stdio.h> 

FILE * stream _ptr; 

Int character; 

) 

LAYER: 1 

STATE: movejndlcator 

CONDITIONS: ENTER^STATE 
ACTIONS: PROMPT “Press O to open file. 

CONDITIONS: KEYBOARD "oO“ 

ACTIONS: 

{ 

lf((stream _plr = fopen(“ FD2/usr/ buf/O I" , "rb")) == 0) 
display _prompt(" Cannot open file, 
else 
{ 

display_prompt("File opened. "); 
posjcursor(0, 14); 

lf(fseek(stream _ptr, 4, SEEK_SET) 1= 0) 
displays (" Improper {seek request, 
else 

displays ("Fseek completed. Press S to seek new position. 

) 

} 

CONDITIONS: KEYBOARD “sS" 

ACTIONS: 

{ 

if(fseek(stream _ptr, -1, SEEKjCUR) I = 0) 

display _prompt(“ Improper fseek request. Press C to close file, 
else 

display _prompt(“ Fseek completed. Press C to close file. 


( 






"); 


M 


); 


fi 


); 
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CONDITIONS: KEYBOARD “cC" 

ACTIONS: 

{ 

lf(fcIose(stream _pir) t- 0) 

display _prompt(" Either file is already closed, or close cannot be executed. ”)} 
else 

display _prompt(" File closed. 

) 


rewind 

Synopsis 

^include <stdlo.h> 

extern void rewindfstream _plr); 

FILE * stream _ptr; 

Description 

This routine returns the file-position indicator to the beginning of the file (i.e., it 
is equivalent to an / seek with the number of characters to move set as zero and 
the specified position SEEKSET). The rewind operation also clears the 
end-of-file and error indicators and erases any memory of the character in a 
previous ungelc operation. 


Inputs 

The only parameter is the stream pointer. 

Example 

In this example, the first call to fgetc following the rewind operation will read the 
first character in the file. 


# include <stdlo.h> 

FILE * stream _ptr; 
int character; 

} 

LAYER: 1 

STATE: movejndlcator 

CONDITIONS: ENTER_STATE 
ACTIONS: PROMPT “Press O to open file. 

CONDITIONS: KEYBOARD "oO‘ 

ACTIONS: 

{ 

;/( (stream _ptr = fopen (“ FD2/usrlbuffOI" , " rb ")) == 0) 

display _prompt(“ Cannot open file. ”)> 

else 

display _prompt(‘‘ File opened. Press S to /seek. "U 

) 
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CONDITIONS: KEYBOARD 'sS' 

ACTIONS: 

{ 

if(fseek(stream _ptr, 4, SEEK_SET) 1= 0) 

display_prompt(“ Improper fseek request. "); 

else 

display _prompt(“ Fseek completed. Press spacebar to rewind. 

} 

CONDITIONS: KEYBOARD * " 

ACTIONS: 

{ 

rewlnd(stream _ptr); 

display _prompt(" Press G to get a character. 

) 

CONDITIONS: KEYBOARD “gG" 

ACTIONS: 

{ 

character =fgetc(stream _ptr); 

display _prompt(“ Press C to close file. ”); 

) 

CONDITIONS: KEYBOARD “cC" 

ACTIONS: 

{ 

if(fclose(stream _ptr) /= 0) 

display jrompt(" Either file is already closed, or close cannot be executed. 
else 

display jromptp'FUe dosed. "); 

} 


lock 

Synopsis 

Uinclude <stdio.h> 

extern void lock(lock_variable _ptr); 

int ' lock_varlable _ptr; 

Description 

The lock routine implements a lock using the integer variable pointed to by the 
routine parameter. If the lock variable is currently locked, the task goes to 
sleep. When an unlock on the same variable occurs (within an independent 
task), the task invoking the lock function will attempt to claim the lock. If 
successful, the task is executed; otherwise, it goes back to sleep until the next 
unlock. 


NOTE: If locking is used at any place in the program, all related 
or possibly concurrent routines must also use the locking 
functions. 
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NOTE: The lock variable should always be defined as a global 
integer, never as local to a function. The lock variable should 
never be altered by the user program or deadlock can occur. 
Deadlock also results if the lock is invoked twice within the same 
task without an intervening unlock. 


Inputs 

The only parameter is a pointer to the lock variable. 

Example 

Two tasks concurrently write to their own file streams. The file streams are local 
to the routine write _fox, making them independent of each other even though 
both are referenced by stream _ptr. During the / close operation (which 
automatically calls /flush), however, both tasks need to write to the same file. 
The locking routines ensure that the writes to the file occur sequentially, not 
concurrently. 

{ 

# Include <sldio.h> 

const char data [] = "(.(.FOX))\n”; 

int key; 

void write Jox() 

FILE • stream _ptr; 
size_t n; 
lock(Akey); 

if ((stream _ptr = fopen("FD2/usrlbuffOI’\ "a”)) == 0) 


display _prompt(" Cannot open file. ”); 

else 

display _prompt(" File opened. 
n = fwritefdata, l, slzeo/(data)~l , stream _ptr); 
pos_cursor(l ,0); 
if(n I = (sizeof(data)-l)) 

disptayf(“Write error. \n”); 

else 

display/ ("Write completed. \n"); 

lf(fclose(Stream _ptr) /= 0) 

display//' Either file is already closed, or close cannot be executed. "); 

else 

display/ (“File closed. "); 


unlock(Akey); 

) 

} 

LAVER: 1 
TEST: a 

STATE: wrlle_and_slgnal 

CONDITIONS: RECEIVE STRING "THE QUICK BROWN FOX" 
ACTIONS: SIGNAL xyz 
{ 

write _fox(); 

) 
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TEST: b 

STATE: wrlte_only 

CONDITIONS: ON SIGNAL xyz 
ACTIONS: 

{ 

write _Jox(); 

) 

unlock 

Synopsis 

Ulnclude <sldio.h> 

extern void uniock(lock_variable _plr); 
int * lock_var!able _ptr; 

Descripji an 

The unlock routine implements the inverse of the lock routine using the same 
integer variable. Sleeping tasks will be woken up to retry their attempt to claim 
the lock, One will succeed, and the rest will go back to sleep. See also lock 
routine. 

Inputs 

The only parameter is a pointer to the lock variable. 

Example 

See lock routine. 


(B) Input-Stream Routines 

The following routines are valid for input streams only. An attempt to apply 
them to output streams results in a read error. The error indicator for the input 
stream will be set. 

Three routines read characters from the input stream. The /read and /gets 
routines transfer a specified number of characters from the stream buffer into a 
user-defined array, fgelc reads the next character from the input stream. The 
ungetc routine temporarily forces a designated character back into the input 
stream. 

fread 

Synopsis 
include <stdio.h> 

extern sizej fread (data j>tr, size, number, stream _ptr); 
void * data _ptr; 
size_t size; 
size_t number; 

FILE * stream _ptr; 
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Description 

This routine reads elements from the input-stream buffer and puts them into a 
user-defined buffer. The file-position indicator is advanced by the number of 
characters successfully read. The / read routine can read a file whose elements 
are more than eight bits each, 16-bit shorts or 32-bit longs, for example. The 
/ gets routine is similar to fread. f gets , however, reads only 8-bit characters. 

The primary use of fread is to read the entire contents of a file, whereas the 
primary purpose of / gets is to read from a file one line at a time. 

Inputs 

The first parameter is a pointer to an array in which the incoming data should 
be placed. 

The second parameter is the number of bytes in each element to be read. If 
the value of this parameter is zero, the contents of the array and the stream 
remain unchanged. 

The third parameter is the number of elements to be read. If the value of this 
parameter is zero, the contents of the array and the stream remain unchanged. 

The fourth parameter is the stream pointer. 

Returns 

The fread routine returns the total number of elements read. If the number of 
elements read is less than the number of elements designated to be read, an 
end-of-file has been encountered or a read error has occurred. Use the feof 
and ferror routines to distinguish an end-of-file from a read error. If an error 
occurs, the location of the file-position indicator is indeterminate. 

Ex am pl e 

Read in a file called “buffOl" from the /usr directory on the disk in drive 2 and 
display it on the Program Trace screen. (See Section 64.4 for information on 
using trace buffers in C.) Determine the size of the array data from the file size 
indicated on the File Maintenance screen. 

{ 

# include <tracejbuf.h> 

Uinclude <stdlo.h> 

FILE * stream _plr; 
char data [6091 ]; 
stzej n; 

extern struct trace_buf progjrbuf; 

) 
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( 


LAYER: 1 

STATE: read_a_flle 

CONDITIONS: ENTER_STATE 
ACTIONS: PROMPT “Press O to open file. 

CONDITIONS: KEYBOARD “oO* 

ACTIONS: 

{ 

Iff (stream _ptr = f open (“ FD2t usrt buffO 1", “r")) -= 0) 

display _prompt(" Cannot open file. ")! 

else 

display_prompt(“Flle opened. Press R to read the file. "); 

> 

CONDITIONS: KEYBOARD *rR" 

ACTIONS: 

{ 

n = freadfdata, 1, 6091, stream _ptr ); 
iffn 1= 6091) 

display _prompt(“ Either a read error has occurred, or an EOF has been 
encountered. "); 

else 

{ 

traceff&prog^Jrbuf, “%. 6091s", data); 

display _prompt(" Press C to close the file. "); 

} 

} 

CONDITIONS: KEYBOARD “oC’ 

ACTIONS: ( 

{ 

ifffclosefstream _ptr) /= 0) 

display _prompt(“ Either file is already closed, or close cannot be executed. "); 
else 

display_prompt(" File closed. "); 

} 


fgets 

Synopsis 
ttinclude <stdlo.h> 

extern char * fgets(string_ptr, maxjtumber, stream_ptr); 
char * string_ptr; 

Int max_number; 

FILE * stream _ptr; 

Description 

This routine gets at the most one less than the specified number of characters 
from an input stream and puts them in an array. If an EOF, newline, or null is 
encountered in the stream, no more characters will be read, even if the specified 
number of characters has not yet been read. The newline will be retained. A 
terminating null character is written after the last character read into the array. 

The file-position indicator is advanced by the number of characters successfully 
read. The fgets routine is similar to f read ■ The fread routine can read a file ( 
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whose elements are more than eight bits each, 16-bit shorts or 32-bit longs, for 
example, fgets, however, reads only 8-bit characters. The primary use of /gets 
is to read from a file one line at a time. 


In puts 

The first parameter is a pointer to the array into which the characters will be 
put. 

The second parameter is the maximum number of characters (minus one) to be 
read. 

The third parameter is the stream pointer. 


Returns 

If the routine is successful, a pointer to the array is returned. If end-of-file is 
encountered before any characters have been read into the array or if a read 
error occurs, a null pointer is returned. The contents of the array are 
indeterminate when a read error occurs. 


Example 

Five characters, at the most, from a disk file will be put into an array called 
data and displayed on the screen. 

{ 

ttlnctude <stdio.h> 

FILE * stream _ptr; 
char data (10]; 

) 

LAYER: 1 

STATE: read_characters 

CONDITIONS: ENTER_STATE 
ACTIONS: PROMPT “Press O to open file. 

CONDITIONS; KEYBOARD "oO” 

ACTIONS: 

{ 

If ((stream j>tr = fopen(" FD2lusrl buffO V , “ r ")) == 0 ) 

dlsp!ay_prompt(“ Cannot open file. "); 

else 

display _prompl(" File opened. Press G to get string. "); 

} 

CONDITIONS: KEYBOARD “qG“ 

ACTIONS: 

{ 

fgets (data, 6, stream _ptr ); 
displayf(“\n%.6s" , data); 

display _prompt(“ Press C to close the file. ”): 

) 
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CONDITIONS: KEYBOARD "cC" 

ACTIONS: 

{ 

if(fclose(stream _ptr ) !- 0) 

display prompt (“Either file is already closed, or close cannot be executed. "); 
else 

display _prompt(“ File closed. "); 


fgetc 

Synopsis 

ttlnclude <stdio.h> 
extern int fgetc(stream _ptr); 

FILE * stream _ptr; 

Description 

The fgetc routine gets the next character (if present) from the input stream. 

The character is an unsigned char cast to an int (stored in the least-significant 
byte of the int). The file-position indicator advances by one character. 

Inputs 

The only parameter is the stream pointer. 

Returns 

This routine returns the next character in the input stream. EOF is returned if 
an end-of-file is encountered or if a read error occurs. The stdio.h file defines 
the macro EOF as -1. Use the feof and ferror routines to determine the reason 
for a returned EOF. 

Example 

In the following example, open an input file for reading. Each time the (o) key 
is pressed, display the next character in the file. 

( 

It include <stdio.h> 

FILE * stream _ptr; 
int character, end; 

) 

LAYER: 1 

STATE: get_next_character 
CONDITIONS: ENTER_STATE 
ACTIONS: PROMPT “Press O to open file. 

CONDITIONS: KEYBOARD “oO“ 

ACTIONS: 

{ 

if((stream _ptr = fopen("FD2lusr!buff01”, " r “)) == 0) 

display jrompt(“ Cannot open file. "): 

else 

display_prompt(“File opened. Press G to get a character. 
displayf("\n "); 
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CONDITIONS: KEYBOARD “gG" 

ACTIONS: 

{ 

character = fgetcfstream _ptr); 
if (character == EOF) 

{ 

end = feof(stream _ptr); 
if(end 1= 0 ) 

display _prompt("EOF encountered, 
else 

display _prompt(“ Read error. 

) 

else 

displayf("%c”, character ); 

} 

CONDITIONS: KEYBOARD “cC‘ 

ACTIONS: 

{ 

if (f dose (stream _ptr) 1= 0) 

display _prompt(“ Either file is already closed, or close cannot be executed 
else 

display _prompt(“ File closed. 

) 

ungetc 

Synopsis 

Uindude <stdlo.h> 

extern int ungetc(character, stream _ptr); 

Int character; 

FILE * stream _ptr; 

Description 

This routine temporarily forces a specified character into a variable associated 
with the input stream, overwriting the previous ungetc variable. The routine 
does not affect the location of the file-position indicator. The next fgetc will 
read the ungetc variable, not the stream. An intervening /flush, /seek, or rewind 
erases memory of the character. If the ungetc function is called too many times 
on the same stream without an intervening read, fflush, fseek, or rewind 
operation on that stream, the operation may fail. Ungetc also clears the 
end-of-file indicator. 

Inputs 

The first parameter is the character to be put into the input stream. 

The second parameter is the stream pointer. 

Returns 

This routine returns the specified character. If the operation fails, EOF is 
returned and the input stream remains unchanged. It will fail if the values of 
the specified character and the macro EOF are equal. 


1 ; 
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Example 

Read a character from the stream. Press the 0 key when you want to return 
the last character read to the stream. The next call to fgelc will read the 
returned character. 

{ 

# include <stdio.h> 

FILE • stream _ptr ; 
int character; 

} 

LAYER: 1 

STATE: get_next_character 
CONDITIONS: ENTER_STATE 
ACTIONS: PROMPT “Press O to open file. 

CONDITIONS: KEYBOARD *oO“ 

ACTIONS: 

{ 

if ((stream _ptr - fopen("FD2lusrlbuff01", "r”)) == 0) 

display _prompt(“ Cannot open file. "); 

else 

display _prompt(“ File opened. Press G to get a character. "); 

) 

CONDITIONS: KEYBOARD “gG" 

ACTIONS: 

< { 

character = fgetcfstream _ptr); 

if (character == EOF ) 

display j>rompt(" End of file or read error. "); 

else 

{ 

pos_cursor(0,0); 

displayff" character = %e Press U to return character to stream.", character); 

} 

} 

CONDITIONS: KEYBOARD *uU“ 

ACTIONS: 

{ 

lf((ungetc(character, stream _ptr )) — EOF) 

display _prompt(“Character not returned. "); 

else 

display _prompt(" Character returned. ”); 

) 

CONDITIONS: KEYBOARD “cC“ 

ACTIONS: 

{ 

if(fclose(stream _ptr) /= 0) 

display jrompt(“Either file is already closed, or close cannot be executed. ”); 
else 

display _prompt(“ File dosed. ”)t 

) 


68-22 


JUL '90 



68 Disk I/O 


(C) Output-Stream Routines 

The following routines are valid for output streams only. An attempt to apply 
them to input streams will result in a write error. The error indicator for the 
output stream will be set. 

Four routines write to output streams. The fwrite and fputs routines transfer a 
specified number of characters from a user-defined array into the stream buffer. 
fputc writes a character to the next empty byte in an output-stream buffer. 
fprintf writes formatted output to an output stream similar to the way display f 
writes output to the Display Window. 


fwrite 

Synopsis 
# include <stdio. h> 

extern size_t fwritefoutput jtr, size, number, stream _ptr); 
const void * output _plr; 
size_t size; 
size_t number; 

FILE * stream jtr; 

Description 

This routine writes elements from a user-defined array to the output-stream 
buffer. The file-position indicator is advanced by the number of characters 
successfully written. 

Inputs 

The first parameter is a pointer to an array from which the data should be 
taken. Declare it as const if it is read-only. In cases where the array will be 
written to, as in the example below, do not include const as part of the 
declaration. 

The second parameter is the number of bytes in each element to be written. 

The third parameter is the number of elements to be written. 

The fourth parameter is the stream pointer. 

Returns 

The / write routine returns the total number of elements written. If the number 
of elements written is less than the number of elements designated to be written, 
a write error has occurred. If an error occurs, the location of the file-position 
indicator is indeterminate. 
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Example 

Read the contents of a file, and write them to a new file. 

{ 

If Include <stdio.h> 

FILE * readstream; 

FILE * wrlte_stream; 
char output 16091); 
size_t n; 

) 

LAVER: 1 

STATE: wrlte_to_a_flle 

CONDITIONS: ENTER_STATE 
ACTIONS: PROMPT 'Press O to open files. 

CONDITIONS: KEYBOARD “oO’ 

ACTIONS: 

< 

if((read_stream = fopen(“ FD2lusrlbuff01" , “ r ")) == 0) 

{ 

display_prompt(“ Cannot open buf/01. "); 
pos_cursor(0,21); 

} 

else 

{ 

display _prompt{“ BuffO 1 opened. ”); 
pos_cursor(0, 16); 

) 

lf((write_stream = fopen("FD2lusr/new_file" , “w”)) == 0) 
displays(“Cannot open new _Jile. 
else 

displays(“New _fl!e opened. Press R to read buffOl. 

) 

CONDITIONS: KEYBOARD “rR" 

ACTIONS: 

< 

n = freadfoutput, 1, 6091, read_jtream ); 
lf(n I = 6091) 

display _prompt(“ Either a read error has occurred, or an EOF has been 
encountered. "); 

else 

display _prompt(“ Press W to write to new JUe. 

} 

CONDITIONS: KEYBOARD “wW" 

ACTIONS: 

{ 

n = fwrlte(output, 1, 6091, write_stream ); 
lf(n != 6091) 

display _prompt (“Write error. Press C to close files, 
else 

displayjprompt ("Write completed. Press C to close files. 


( 


'); 


"); 


#> 


1 ; 


1 ; 


ii 


): 
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CONDITIONS: KEYBOARD “cC‘ 

ACTIONS: 

{ 

tf(fdose{read_stream) /= 0 ) 

{ 

display _prompt(“ Either buffOl Is already closed, or close cannot be executed, "); 
pos_cursor(0,0); 

) 

else 

{ 

display _prompt(“ BuffO I closed. "); 
poscursor (0,16); 

) 

lf(fdose(wrlte_Stream) t- 0) 

displays(“Elther new _JHe is already dosed, or dose cannot be executed. "); 

else 

displays ("New Jile dosed. 


fputs 

Synopsis 

Hindude <stdio.h> 

extern Int fputs(slring_ptr, stream _ptr); 
const char * strlngj>tr; 

FILE • stream _ptr; 

Description 

This routine writes a string of characters from an array, excluding the 
terminating null character, to the output stream. The file-position indicator is 
advanced by the number of characters successfully written. 

Inputs 

The first parameter is a pointer to the string to be written. 

The second parameter is the stream pointer, 

R etu rns 

This routine returns zero if it is successful; it returns a non-zero value if a write 
error occurs. 

Examp le 

Write a fox message at the end of existing data in a file. 

{ 

It Include <stdio.h> 

FILE • stream _ptr; 

char data [] = “(( FOX))\n"; 

) 
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LAYER: 1 

STATE: wrlte_a_strfng 

CONDITIONS: ENTER_STATE 
ACTIONS: PROMPT “Press O to open file. 

CONDITIONS: KEYBOARD “oO" 

ACTIONS: 

< 

iff (stream _j>tr = fopen("FD2/usr/buff01”, "a")) == 0) 

display _prompt(“ Cannot open file. "); 

else 

display _prompt(“ File opened. Press P to write siring. "); 

} 

CONDITIONS: KEYBOARD “pP" 

ACTIONS: 

{ 

if (f puts (data, stream _ptr) 1= 0 ) 

dlsplay_prompt(" Write error. Press C to close file. 
else 

display _prompt (“Write completed. Press C to dose file. "); 

) 

CONDITIONS: KEYBOARD “cC’ 

ACTIONS: 

{ 

ifffclosefstream _ptr) 1= 0) 

display _prompt(“ Either f ile is already closed, or close cannot be executed. 
else 

display _prompt(" File dosed. 


fputc 

Synopsis 
Uinclude <stdio.h> 

extern int fpulcfcharacter, stream _ptr); 
int character; 

FILE * stream _ptr; 

Description 

This routine writes a given character (cast to an unsigned char) to an output 
stream. The file-position indicator advances one character. 

Inputs 

The first parameter is the character to be written to the output stream. It may 
be given as a hexadecimal, octal, or decimal constant: as an alphanumeric 
constant inside single quotes: or as a variable. A hexadecimal value must be 
preceded by the prefix Ox or OX; an octal value must be preceded by the prefix 
0. If no prefix appears before the input, the number is assumed to be decimal. 

The second parameter is the stream pointer. ( 
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Returns 

If the character is successfully written to the output stream, the routine returns 
that character, If a write error occurs, EOF is returned and the error indicator 
is set. 

Ex ampl e 

Open the named file. If the file does not already exist, create it. If it does 
exist, truncate its length to zero, thereby deleting its contents. Put the character 
read from the input stream pointed to by read_stream into the output stream 
pointed to by write_stream. This example is similar to the one given for /write, 
except that in this case, each lime the 0 key is pressed, only one character is 
copied, rather than the entire file. 

{ 

ft include <stdio.h> 

FILE ‘ read_stream; 

FILE * write_stream; 

Ini character; 

) 

LAYER: 1 

STATE: copy_a_charaoter 

{ CONDITIONS: ENTER_STATE 

ACTIONS: PROMPT "Press O to open flies. 

CONDITIONS: KEYBOARD "oO' 

ACTIONS: 

{ 

lf((read_slream = fopen(" FD2lusrlbuff01" , "r")) == 0) 

< 

display _prompt('‘Cannot open buf/01. "); 
posj:ursor(0,2I); 

) 

else 

{ 

display _prompl(“ BuffO 1 opened. 
pos cursor(0, 16) ; 

) 

lf((write_stream = fopen(“FD2lusrlbuffOI_copy", "w")) == 0) 

displays(“Cannot open buff01_copy. "); 

else 

displays (“ BuffO I _copy opened. Press P to copy a character. ”); 

) 

CONDITIONS: KEYBOARD “pP" 

ACTIONS: 

{ 

character = fgetc(read_stream ); 
if(character == EOF) 

{ 

lf(feof(read_slream) 1= 0) 

display _prompt(“EOF encountered. Press C to close files. "); 

else 

display _prompt(“ Read error. Press C to close files. "); 

> 
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else 

fputcfcharacter, wrlte_stream); 

} 

CONDITIONS: KEYBOARD “cC" 

ACTIONS: 

< 

if(fclose(read_stream) /= 0) 

{ 

display j)rompt(" Either buf/01 is already closed, or close cannot be executed. ”); 
pos_cursor(0,0 ); 

) 

else 

{ 

display _prompt(" Buf/01 closed. "); 
pos_cursor(0, 16); 

) 

if(fclose(write_stream) /= 0) 

display/ (“Either buf/01 _copy is already closed, or close cannot be executed. ”); 
else 

display (" BuffO 1 jtopy closed. "); 


fprlntf 

Synopsis { 

^include <stdio.h> 

extern int /print/ (stream _ptr, format _ptr, ...); 

FILE * stream _ptr; 
char * format _plr; 


Description 

The fprintf routine is similar to the sprintf routine, except that fprintf writes 
output to an output stream, while sprintf writes output to an array. The output 
is under control of the string pointed to by format _ptr that specifies how 
subsequent arguments are converted for output. If there are insufficient 
arguments for the format, the behavior is undefined. If the format is exhausted 
while arguments remain, the excess arguments are evaluated but otherwise 
ignored. The fprintf routine returns when the end of the format string is 
encountered. ( Sprintf is documented in Section 67.3.) 

Inputs 

The first parameter is the stream pointer. 

The second parameter points to the format string composed of zero or more 
directives: ordinary characters (not %), which are copied unchanged to the 
output stream - , and conversion specifications, each of which results in fetching 
zero or more subsequent arguments. Each conversion specification is introduced 
by the character %. After the %, the following appear in sequence: ( 
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• Zero or more flags that modify the meaning of the conversion specification. 
The flag characters and their meanings are: 

The result of the conversion will be left-justified within the field. 

+ The result of a signed conversion will always begin with a plus or 
minus sign. 

space If the first character of a signed conversion is not a sign, a space will 
be prepended to the result. If the space and + flags both appear, the 
space flag will be ignored. 

# The result is to be converted to an “alternate form.” For d, i, c, and 
s conversions, the flag has no effect. For o conversion, it increases 
the precision to force the first digit of the result to be a zero. For x 
(or X) conversion, a nonzero result will have Ox (or OX) prepended to 
it. 

• An optional decimal integer specifying a minimum field width. If the 
converted value has fewer characters than the field width, it will be padded 
on the left (or right, if the left adjustment flag, described above, has been 
given) to the field width. The padding is with spaces unless the field width 
integer starts with a zero, in which case the padding is with zeros. 

• An optional precision that gives the minimum number of digits to appear for 
the d, i, o, u, x, and X conversions or the maximum number of characters 
to be written from an array in an s conversion, The precision takes the 
form of a period (.) followed by an optional decimal integer; if the integer is 
omitted, it is treated as zero. The amount of padding specified by the 
precision overrides that specified by the field width. 

• An optional h specifying that a following d, i, o, u, x, or X conversion 
specifier applies to a short ini or unsigned short int argument (the argument 
will have been promoted according to the integral promotions, and its value 
shall be converted to short int or unsigned short int before printing); or an 
optional 1 specifying that a following d, i, o, u, x, or X conversion specifier 
applies to a long int or unsigned long int argument. If an h or 1 appears 
with any other conversion specifier, it is ignored. 

• A character that specifies the type of conversion to be applied. (Special AR 
extensions have been added,) The conversion specifiers and their meanings 
are: 
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( 


d, i, o, u, x, X 

The int argument is converted to signed decimal (d or i), unsigned 
octal (o), unsigned decimal (u), or unsigned hexadecimal notation (x 
or X); the letters abcdef are used for x conversion and the letters 
ABCDEF for X conversion. The precision specifies the minimum 
number of digits to appear; if the value being converted can be 
represented in fewer digits, it will be expanded with leading zeros. 

The default precision is 1. The result of converting a zero value with 
a precision of zero is no characters. 

c The int argument is converted to an unsigned char, and the resulting 
character is written. 

s The argument shall be a pointer to a null-terminated array of 8— bit 

chars. Characters from the string are written up to (but not including) 
the terminating null character: if the precision is specified, no more 
than that many characters are written. The string may be an array 
into which output was written via the sprintf routine. 

p The argument shall be a pointer to void. The value of the pointer is 
converted to a sequence of printable characters, in this format: 

0000:0000. There are always exactly 4 digits to the right of the 
colon. The number of digits to the left of the colon is determined by ' 
the pointer’s value and the precision specified. Use this conversion to 
display 80286 memory addresses. The 16-bit segment number will 
appear to the left of the colon and the 16-bit offset to the right. 

% A % is written. No argument is converted. 

\n Writes hexadecimal 0A, the ASCII linefeed character. No argument 
is converted. 

If a conversion specification is invalid, the behavior is undefined. 

If any argument is or points to an aggregate (except for an array of characters 
using %s conversion or any pointer using %p conversion), the behavior is 
undefined. 

In no case does a nonexistent or small field width cause truncation of a field; if 
the result of a conversion is wider than the field width, the field is expanded to 
contain the conversion result. 

Returns 

This routine returns the number of characters written, or a negative value if an 
output error occurred. 

Example 

i 

Assume the X.25 personality package has been loaded in at Layer 2. When an 

unknown frame is received, copy the actual value of the control byte to an 

output stream. [ 
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{ 

tf Include <stdlo.h> 

FILE * stream _ptr; 

extern volatile const unsigned char rcvd _frame_cntri_byle_l; 

) 

LAYER: 2 

STATE: save_unknowns 

CONDITIONS: ENTER_STATE 
ACTIONS: PROMPT ‘Press O to open file. 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

if ((stream _ptr = fopen(“FD2lusrlframejjnkwn", “w") ) == 0) 
display _prompt(“ Cannot open file. 
else 

display _prompt("File opened. 

) 

CONDITIONS: RCV UNKNOWN 
ACTIONS: 

{ 

If (fprlntf (stream _plr, “ %02x\n”, rcvd _frame_cntri_byte_l) < 0) 

display _prompt(“ Error in printing to stream. ”)>' 

else 

display _prompt(" Print to stream completed. Press C to close file. “); 

) 

CONDITIONS: KEYBOARD “cC" 

ACTIONS: 

{ 

lf(fclose(stream j>tr) /= 0) 

display _prompt(“ Either file is already closed, or close cannot be executed. "); 
else 

display j>rompt(" File closed. "); 

} 


(D) File Maintenance Routines 
rename 

Synopsis 

# include <stdio.h> 

extern ini rename (oldf He _ptr, newfile _ptr); 
const char * oldfile j>tr; 
const char * newfile _ptr; 

Description 

This routine renames a specified file. A file can only be renamed if it resides 
on the active disk, indicated on the Current Directory line of the File 
Maintenance screen. Renaming an open file does not affect subsequent disk I/O 
operations on the stream. The stream is still associated with the same file, even 
though the filename has changed. 
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Inputs 

The first parameter is a pointer to a string, the current name of the file. Give 
the absolute pathname of the file, prefixed by the device name (HRD, FD1, or 
FD2). 

The second parameter is a pointer to a string, the new name to be given to the 
file. Give the absolute pathname of the file, prefixed by the device name. 

Returns 

If the rename operation succeeds, zero is returned. If it fails, a non-zero value 
is returned. If the renaming fails, the file will still be known by its original 
name. 

Example 

Change the name of a file from old to backup. Prompt whether or not the 
rename operation was successful. 

{ 

t (include <stdio.h> 

) 

LAYER: 1 

STATE: rename 

CONDITIONS: ENTER_STATE ( 

ACTIONS: PROMPT “Press spacebar to rename file. 

CONDITIONS: KEYBOARD “ ’ 

ACTIONS: 

{ 

lf(rename(“FDl lusr/old”, “FD1 tusr/backup") 1= 0) 

display_prompl(“ Rename failed. "); 

else 

display _prompt(“File has been renamed. 

> 

remove 

Synopsis 

it include <sidio.h> 
extern int remove (file _ptr); 
const char * file _pir; 

Description 

This routine removes the named file from the disk. The file must be closed in 
order for the remove operation to succeed. Subsequent attempts to open the 
file will fail. Empty directories may also be removed with this routine. 

Inputs 

The only input is a pointer to a string, i.e., the filename. It must be the 

absolute pathname, prefixed by the device name (HRD, FD1, or FD2) . ( 
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Returns 

Zero is returned if the file is removed; non-zero if it is not (for example, the 
file does not exist in the specified location). 

Example 

Remove file oldfile from the /usr directory on the disk in floppy drive 1. 

Prompt whether or not the remove operation was successful. 

\ 

# include <stdlo.h> 

) 

LAYER: 1 

STATE: delete_ajlle 

CONDITIONS: ENTER_STATE 
ACTIONS: PROMPT “Press D to delete file. 

CONDITIONS: KEYBOARD “dD" 

ACTIONS: 

{ 

if (remove (“FD1 1 usr I oldfile") != 0) 

display _prompt("File has not been deleted. "); 

else 

display _prompt(" File deleted. "); 

} 


mkdlr 

Svnonsis 

ttindude <stdio.h> 

extern int mkdir(directory_ptr) ; 

char * directory _plr; 

Description 

This routine creates a directory. 

Inp ut s 

The only parameter is a pointer to a string, i.e., the name of the directory to be 
created. The absolute pathname must be used, prefixed by the device name 
(FD1, FD2, or HRD) , 

Returns 

If the directory is created, zero is returned; otherwise, a non-zero value is 
returned. 

Example 

Create a sub-directory called disk_i_o in the lusr directory on the disk in 
drive 2. 

{ 

itinclude <stdio.h> 

) 
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LAYER: 1 

STATE: make_directory 

CONDITIONS: ENTER_STATE 

ACTIONS: PROMPT 'Press M to make a directory, ’ 

CONDITIONS: KEYBOARD “mM" 

ACTIONS: 

if(mkdlr(“FD2/usr/dlsk_i_o”) /= 0) 

display _prompt(“ Directory not created. "); 

else 

display _prompt(“ Directory created. ”); 

) 

_set_flle_type 

Synopsis 
tt include <stdio.h> 

extern ini _sel JHeJype (pathname _ptr, typejbuff j>tr); 
char * pathname _plr; 
char * type_bu/f_ptr; 

Dgscrip lion 

This routine determines the type identification of a specified file on the File 
Maintenance screen. If a file is created by a "w” or “a" open mode and a file 
type is not specified with the _set JUejype routine, it will be designated as an 
ASCII file. Note, however, that it is the file’s contents, not its label, that 
determines which functions are valid for the file (see example). 

Inputs 

The first parameter is a pointer to a string, the name of the file. The filename 
must be the absolute pathname, prefixed by the device name (HRD, FD1, or 
FD2). 

The second parameter is a pointer to a string, the file type. The type may be 
any of the following (upper or lower case is acceptable): 


SYS 

System 

DIR 

Directory 

PRGM 

Program 

SETUP 

Setup 

OBJ 

Object code 

LOBJ 

Linkable object 

LPGM 

Linkable program 

ASCII 

ASCII 

BITIM 

Bit-image data 

CHDAT 

Character data 
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Returns 


If the operation succeeds, the routine returns zero; otherwise, it returns a 
non-zero value. 


Example 

The following example is almost the same one used for / write : read the contents 
of a program file and write them to a new file. The difference is that new _file is 
set to be a program file. In the fwrite example, the type designation in the file 
directory would default to "ASCII.” It would still load and run as a program 
file, however, since the file’s contents, not its type label, determine which 
operations are valid. 


{ 

ttinclude <stdlo.h> 

FILE * read_stream; 

FILE * write_stream; 
char output [6091]; 
size_t n; 

} 

LAYER: 1 

STATE: wrfte_to_a_flle 

CONDITIONS: ENTER_STATE 
ACTIONS: PROMPT “Press O to open files. 

CONDITIONS: KEYBOARD “oO“ 

ACTIONS: 

{ 

lf((read_stream = f open (" F D2 ! usr t buff 01" , “r”)) == 0 ) 

{ 

display_prompt(“Cannot open buffOl. "); 
pos_cursor(0,21); 

} 

else 

{ 

display j)rompt(“ BuffOl opened. "); 
pos_cursor(0, 16); 

} 

if((wrlte_stream = fopen(“FD2lusrinew _file”, "w” )) == 0) 

displays ("Cannot open new _file. "); 

else 

dlsplays(“New _Jile opened. Press “sS" to set the file type. "); 

) 

CONDITIONS: KEYBOARD “sS" 

ACTIONS: 

< 

if(_set Jite_type(“FD2lusrlnew Jile", "PRGM’’) 1= 0) 

display _prompt(" File type not set. Press R to read buffOl. ")>' 

else 

display _prompt(" File type set. Press R to read buffOl . ”); 

} 
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CONDITIONS: KEYBOARD YR' 

ACTIONS: 

{ 

n = freadfoutput , J, 6091, read_stream); 
if(n /= 6091) 

display _prompt(“ Either a read error has occurred, or an EOF has been 
encountered. "); 
else 

display _prompt(“ Press W to write to new __ file . "); 

) 

CONDITIONS: KEYBOARD “wW" 

ACTIONS: 

< 

n = fwritefoutput, 1, 6091, write_slream); 
tf(n /= 6091) 

dlsplay_prompt("Wrlte error. Press C to close files. "); 

else 

disptay_prompt(“Write completed. Press C to close files. "); 

} 

CONDITIONS: KEYBOARD “cC’ 

ACTIONS: 

{ 

if(fclose(read_stream ) 1= 0) 

{ 

display ^prompt (“ Either buffO 1 is already closed, or close cannot be executed. "); 
pos_cursor(0,0); 

) 

else 

{ 

display j>rompt(“ BuffO 1 closed. "); 
pos_cursor(0, 16); 

} 

if (fclose (write stream) /= 0) 

displaysC'Either new Jile is already closed, or close cannot be executed. "); 

else 

displays("New file dosed, "); 

} 

_get_file_type 

Synopsis 

it include <stdio.h> 

extern int _getjile_type(pathname _ptr, type_buff_ptr); 
char * pathname _plr; 
char * type_buff_ptr; 

Description 

This routine determines the type of a specified file. 

Inputs , 

The first parameter is a pointer to a string, the name of the file. The filename 
must be the absolute pathname, prefixed by the device name (HRD, FD1, or 
FD2). 
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The second parameter is a pointer to an array in which the file type should be 
written. See _set_file_type for the different file types. 

Returns 

If the operation succeeds, the routine returns zero; otherwise, it returns a 
non-zero value. 

Example 

< 

# Include <stdio.h> 

FILE * stream _ptr; 
char type ( 8 ]; 

) 

LAYER: 1 

STATE: flndjype 

CONDITIONS: ENTER_STATE 

ACTIONS: PROMPT “Press Q to get file type. 

CONDITIONS: KEYBOARD “gG“ 

ACTIONS: 

{ 

_file_type("FD2lusrlnew _file", &type{0 ]) I = 0) 
display _prompt(“ File type not found. 
else 

displayfC'Fite lype=%s. ", type); 

) 
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69 Status 


The structures and variables referenced in this section provide information about the current 
status of the programmer’s INTERVIEW. This information must be accessed via C coding on 
the Protocol Spreadsheet since these structures and variables have no softkey equivalents. 

69.1 Unit Configuration 

Two structures presented in Table 69-1 may be accessed by the user to identify 
current features of the INTERVIEW. unit_setup variables reflect current Line Setup 
menu and FEB tick-rate selections. unit_config variables contain information about 
the user’s INTERVIEW hardware and software. 

69.2 Current Display Mode 

The variables display _screen_changed, crnt_display_screen, and prev_display_screen 
track movement via softkey from one display screen to another. These variables also 
indicate transitions between Run mode and Freeze mode. They are documented in 
Section 64.1. 
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Table 69-1 
Status Structures 


Type Variable Value (hex/decimal) 


Meaning 


Structure Name: unit_setup Structure containing Line Setup and FEB tick-rate 

selections. Declared as type extern struct. 
Reference member variables of the structure as 
follows: unit _setup. speed _dce. 


unsigned long 

speed_dce 


If Clock Source selection is Internal, this variable 
has Speed value entered on Line Setup. If Clock 
Source Is External, this variable has DCE speed 
Indicated under Clock Source: Internal Split. 

unsigned long 

speed_dte 


If Clock Source selection Is Internal, this variable 
has Speed value entered on Line Setup. If Clock 
Source Is External, this variable has DTE speed 
Indicated under Clock Source: Internal Split. 

unsigned long 

usec_per_tlck 

a/10 

tfck rate selected on FEB Setup 
10 useo 



64/100 

100 usee 



3e8/1000 

1 msec 



2710/10000 

10 msec 



186a0/ 100000 

1000 msec 



14240/1000000 

1 sec 

unsigned char 

blt_order_polarlty 

0 

normal 



1 

normal-inverse 



2 

reverse-normal 



3 

reverse-inverse 

unsigned char 

blts_per_byte 

5-8 


unsigned char 

clocklng_type 

0 

Internal 



1 

external 



2 

Internal-split 

unsigned char 

data_source 

0 

disk 



1 

line 

unsigned char 

format 

0 

sync 



1 

bop 



2 

async 



3 

Isoc 

unsigned char 

mode 

0 

automonitor 



1 

monitor 



2 

emulate dee 



3 

emulate dte 

unsigned char 

parity 

0 

none 



1 

even 



2 

odd 



3 

mark 



4 

space 

unsigned char 

code name (13) 


ASCII, EBCDIC, etc. 
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Table 69-1 (continued) 


Typo 

Variable 

Value (hex/dacimal) 

Meaning 


Structure Name: unit config 


Structure containing unit configuration. Declared 




as type extern struct. Reference member 
variables of the structure as follows: 




unlt_conflg . Poppy jextstsmask . 

unsigned char 

floppy exists mask 

1 

floppyl 



2 

floppy2f 

unsigned char 

hard disk 

0 

not present 



1 

present 

unsigned char 

test board 

0 

not present 



1 

present 

unsigned char 

mux 

0 

not present 



1 

present 

unsigned char 

modem 

0 

not present 



1 

present 

unsigned char 

nummpms 

0-4 

number of MPM boards present 

struct nnpmjnfo 

mpm [4] 


array of structures. Each element In the array Is 
an Instance of the structure mpmjnlo and 
corresponds to one of four MPM boards which 
may be present. Reference member variables of 
the structure elements in the array as follows: 
unlt_conflg . mpm[0 ] . present. 

unsigned char 

cpm rev 

0, 7f/0, 127 

original CPM board 



1-UI1-31 

TURSO-compatlble CPM board 



20-7 e 132-1 26 

4-Mbyte, Tl/RSO-compatlble CPM board 

unsigned char 

gbm_rev 

0, ff/0, 256 

original QBM board 

unsigned char 

pern rev 

0, ff/0, 256 

original PCM board 



1 

44-Mbyte hard disk compatible PCM board 

unsigned char 

modem_rev 


reserved 

unsigned char 

mux_rev 


reserved 

unsigned char 

tlm type 

f0/240 

RS-232 



f 1/241 

X.21 



f 2/242 

V.35 



f3/243 

RS-449 



f4/244 

expansion adaptor 



f5/245 

RC-8245 



f6-(b/246-251 

reserved 



fc/252 

ISDN 



fd/253 

G.703 



fe/254 

T1 



ff/255 

none 

unsigned long 

last ram cpm 


the value of this variable plus one yields the CPM 



memory size (In bytes) 



(unlt_conflg continued on next page) 


t If (unit jtonflg .floppy _exlsts_mask & value) == value, the drive Is present. 

For example, If (unlt_conflg.floppy_exlst$_ma$k & 2) == 2, floppy drive 2 Is present. 
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Table 69-1 (continued) 


Type 

Variable 

Value (hex/decimal) 

Meaning 

unsigned long 

self_test_errors 

(mask) 

self-test errors encountered during 

power-uptt 



1 

CPM DRAM error 



2 

CPM 32— bit counter 



4 

CPM System Timing Controller (9513a) 



8 

CPM DMAC 



10/16 

MPM0 DRAM (tested from CPM-global bus) 



20/32 

MPM0 DRAM (tested from MPM0) 



40/64 

MPM0 Interrupt latch 



80/128 

unused 



100/256 

MPM1 DRAM (tested from CPM-global bus) 



200/512 

MPM1 DRAM (tested from MPM1) 



400/1024 

MPM1 Interrupt latch 



800/2048 

unused 



1000/4096 

MPM3 DRAM (tested from CPM-global bus) 



2000/8192 

MPM3 DRAM (tested from MPM3) 



4000/16384 

MPM3 Interrupt latch 



8000/32768 

unused 



10000/65536 

unused 



20000/131072 

unused 



40000/262144 

unused 



80000/524288 

unused 



100000/1048576 

unused 



200000/2097152 

unused 



400000/4194304 

unused 



800000/8388608 

unused 



1000000/16777216 

unused 



2000000/33554432 

unused 



4000000/67108864 

unused 



8000000/134217728 

unused 



10000000/268435456 

unused 



20000000/536870912 

unused 



40000000/1073741824 

unused 



80000000/2147483648 

unused 

unsigned long 

version 

9 

current value for this version of unlt_con(lg 
structure 

unsigned long 

model number 

19C8/6600 

INTERVIEW 6600 


1a90/6800 

INTERVIEW 6800 TURBO 



1b58/7000 

INTERVIEW 7000 



1C20/7200 

INTERVIEW 7200 TURBO 



1d4c/7500 

INTERVIEW 7500 



1 e 14/7700 

INTERVIEW 7700 TURBO 

unsigned char 

feb_type 

0 original version 

1 version with Increased speed of software and 



faster access to ticks from FEB 



2 version which supports high-speed RAM 



recording, specifically aggregate T1 or G.703 
data capture 



3 version which also supports INTERVIEW 7200 and 



7700 TURBOS 



(ur>lt_conflg continued on next page ) 


tt It (unlt_conflg.sell_test_errors & mask) == mask, the error Is present. 

If (unlt_contlg . sel(_testjerrors & Oxll(tftlf) == 0, no errors encountered during power-up. 
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Table 69-1 

(continued) 

Type 

Variable 

Value (hex/decimal) Meaning 

unsigned char 

Is turbo 

0 

unit Is not TURBO 



1 

unit Is TURBO 

unsigned char 

xdram_rev_num 


XDRAM revision number 

unsigned char 

xdram present 

0 

XDRAM board Is not present 



1 

XDRAM board Is present 

unsigned long 

xdram_lo_addr 


low end of memory range 

unsigned long 

xdram_hl_addr 


high end of memory range 

unsigned char 

reserved 


reserved 

unsigned char 

hard disk type 

0, 2 

20-Mbyte disk 



3 

44-Mbyte disk 

unsigned char 

xtlm installed 

0 

TIM-expanslon shelf Is not present 



1 

TIM-expansion shelf Is present 

unsigned char 

xsys ram present 

0 

additional system memory Is not present 



1 

additional system memory Is presen 

unsigned long 

xsysramloaddr 


low end of memory range 

unsigned long 

xsys_ram_hl_addr 


high end of memory range 

unsigned long 

spare 1 


reserved/undefined 

unsigned long 

spare2 


reserved/undefined 

unsigned long 

spare3 


reserved/undefined 

unsigned long 

spare4 


reserved/undefined 

unsigned long 

spare5 


reserved/undefined 

unsigned long 

spares 


reserved/undefined 

unsigned tong 

spare7 


reserved/undefined 

unsigned long 

sw_verslon 


software verslonttt 

unsigned long 

fw_verslon 


firmware verslonttt 

Structure Name: mom info 


Structure containing Information on specific MPM 




board. Instance of this structure for each MPM 
board Is contained In array named 
unitjconUg.mpm. Declared as type extern 
struct. 

unsigned char 

rev_num 


MPM revision number 

unsigned char 

present 

0 

specific MPM board (of four) not present 


1 

specific MPM board (of four) present 

unsigned long 

loaddr 


low end of memory range 

unsigned long 

hl_addr 


high end of memory range 


tttTo display the software version In the same format presented on the main menu screen, 5.00 for example, use the 
following format In a call to display I (or trace f) : 

dlsplayf(“ %lu. %02lu%c' , ((unlt_con(!g.sw_verslon » 8)1100), ((unlt_conftg.sw_ver$lon » 8)%100), 

(char) (unlt_contlg ,sw_verslon & Oxff)); 

The same format may be used for presentation of the firmware version. 
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70 Remote Port I/O 


The REMOTE RS-232 port is a “spare” serial interface through which the programmer may 
communicate with other equipment. The remote port is located at the rear of the 
INTERVIEW next to the printer port. (The REMOTE LED on the front panel of the 
INTERVIEW is related to remote control of the unit, unimplemented at this time.) 

Remote-port functions must be coded in C regions on the Protocol Spreadsheet. There are 
no spreadsheet-token equivalents of the C variables and routines described in this section. 

Use these variables and routines in either emulate or monitor mode to transmit and receive 
data through the remote port. 

The remote-communications process on the CPM controls the flow of data between the user’s 
program and the remote port. When data is received through the remote port, this process 
temporarily buffers it in a 2048-byte input queue. The user’s program makes requests for 
data from the input queue via the rmt_getc, rmt_getl, and rmt_gets input routines discussed 
below. When the remote-communications process receives a request, it removes data from 
the queue and passes it to the task. If there are no outstanding requests at the time data is 
received, it is discarded from the input queue— i.e., data received between requests cannot be 
retrieved. This is the default condition of the input queue. 

To “lock” all received characters in the input queue, call rmt Jock. When the input queue is 
locked, the remote-communications process removes data only when 1) a user task has 
requested data via the rmt _getc, rmt _getl, or rmt_gets routine, 2) the input queue is full and 
some data must be discarded in order for incoming data to be buffered, or 3) rmt Jlushi is 
executed. "Unlock" the input queue with rm(_unlock. rmt_unlock, rmt Jlushi, and 
rmtjlusho are automatically executed whenever the INTERVIEW returns to Program mode. 


NOTE: Although requests to receive (or transmit) data from more 
than one task are queued by the remote-communications process, 
a single task can have only one such request outstanding at a time. 


Similarly, when the programmer wants to send data out the remote port, he calls rmt_putc, 
rmt _puts, or rmt _putb. The remote-communications process temporarily places these requests 
in an output queue before transmitting them through the remote port. 


70.1 Structures 

There are no structures associated exclusively with remote functions. 
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70.2 Variables 

Table 70-1 lists the event variables specific to remote port I/O operations. Use most 
of these variables to detect changes in the status of the input and output queues. 

As data is received through the remote port, the remote-communications process 
temporarily stores it in the input queue. Use rmt_input_notjempty, 
rmtJnput_almost Jull, and rmt_input_overflow to monitor how full the input queue 
is. When the input queue is "almost full," incoming data must be stopped in order 
to prevent the queue from overflowing. 

rmtJnput_almost_empty and rmtjnput_empty are significant events as the remote 
communications process takes data out of the input queue. These events indicate 
that that the input queue is ready to accept more data. 


( 


( 
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Table 70-1 

Remote Port I/O Variables 

Type 

Variable 

Value (hex/decimal) Meaning 

extern event 

» 

rmt_break 


True when a break (NULL with a 
framing error) Is received 
through the remote port. Line 
Setup configured for emulate or 
monitor mode. 

extern event 

rmt_lnput_not_empty 


True when remote Input-queue 
transitions from empty to not 
empty. Beginning to receive 
characters. Line Setup 
configured for emulate or 
monitor mode. 

extern event 

rmt_lnput_almost_fuH 


True when the remote 
Input-queue transitions from 
less than 3/4 full to 3/4 full as 
data Is being put Into the queue. 
Line Setup configured for 
emulate or monitor mode. 

extern event 

rmt_lnput_overflow 


True when remote Input-queue 
. transitions from not full to full. 

At this point, the oldest existing 
data In the queue Is discarded 
to make room for new data 
coming In the remote port. Line 
Setup configured for emulate or 
monitor mode. 

extern event 

rmt_lnput_almost_empty 


True when the remote 
Input-queue transitions from 
more than 1 /4 full to 1 / 4 full as 
data Is being taken out of the 
queue. Line Setup configured 
for emulate or monitor mode. 

extern event 

rmtjnput_empty 


True when remote Input-queue 
transitions from not empty to 
empty. All characters have 
been read or discarded. Line 
Setup configured for emulate or 
monitor mode. 

extern event 

rmt_output_empty 


True when remote output-queue 
transitions from not empty to 
empty. All data output to the 
remote port has been 
transmitted. Line Setup 
configured for emulate or 
monitor mode. 
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70.3 Routines 

Remote routines fall into three categories. Input routines are used to read data 
received from the remote port. Use output routines to transmit data through the 
remote port. The last category of routines reads or sets parameters for the remote 
port. 


(A) Input Routines 

Use rmt _getc, rmt _getl, and rmt_gets to read data received through the remote 
port. Use rmt Jock and rmt_unlock to control the flow of data from the input 
queue. 

rmt_getc 

Synopsis 

extern int rmt_getc(wait) ; 
int wait; 


Description 

The rmtj>etc routine reads the next character (if present) from the remote port. 

Inputs 

If no character is available from the input queue when rmt_getc is called, this 

parameter determines when the routine will return 1 . 

• Specify a timeout value in the hexadecimal range °o°i through f f f e (decimal 1 
through 65534) to indicate how long the routine should wait for a character 
to become available before returning. During this waiting period, no other 
conditions and actions within the same state will be executed. (The extern 
event variable rmtJnput_not_empty in Table 70-1 can be used to indicate 
when data is received,) 

At the end of the timeout, the routine returns without a character if none is 
available. Timeout values represent tenths of a second. If another task has 
already requested data from the queue, this request will be queued. 

• When the value is hexadecimal f f f f , the routine does not return until a 
character becomes available. If another task has already requested data 
from the queue, this request will be queued. 

• When the value is zero, the routine returns without a character if none is 
available. If there is already an outstanding request from another task, a 
zero value also causes the remote-communications process to return from 
the routine without checking the input queue. 
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NOTE: More than one test (task) may request data from the 
input queue. The remote-communications processes queues these 
requests as they are made. To ensure that requests are processed 
in turn, use this "wait” parameter consistently across tests. If you 
set the parameter to a non-zero value in a call to rmt_getc (or 
rmtjfets) in one test, do the same in all tests, 

Returns 

If a character is present in the input queue, this routine returns the character (as 
an ini) read. If no character is present and the routine’s “wait” parameter is 
zero or the timeout expires, a -1 is returned. When the parameter is zero, a -1 
also is returned if there is already an outstanding request from another task. 

Example 

In the following example, the routine does not wait for a character to become 
available in the remote port before returning. Each time the ® key is pressed, 
the next character, if present, is displayed. If a -1 is returned instead of a 
character, a message to that effect will be displayed on the prompt line. 

LAVER: 1 

STATE: get next_character 
CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

display _prompt(" Press C to get next character. "); 

rmt_lock(); 

) 

CONDITIONS: KEYBOARD "cC’ 

ACTIONS: 

1 

Int character; 
character = rmt_getc(0); 
if (character == -1) 

display _prompt(“ No character available. "); 

else 

displayf("%c”, character ); 

) 

rmt_getl 

Synopsis 

extern int rmt_getl(string_ptr, maxjength); 
char * stringjtr; 
int max_lenglh; 

Description 

rmtjzetl reads from the remote port one line at a time. This routine gets at the 
most the specified number of characters from the remote port and puts them in 
an array. Unless a carriage return or linefeed is encountered, the routine does 
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not return until the specified number of characters has been read. A carriage 
return or linefeed causes the routine to return, even if the specified number of 
characters has not yet been read. The carriage return or linefeed is replaced by 
a terminating NULL character in the array. 

Inputs 

The first parameter is a pointer to the array into which the characters will be 
put. 

The second parameter is the maximum number of characters to be read, 

Returns 

This routine returns the number of characters (preceding the terminating NULL) 
read into the array. 

E x a m ple 

Each time the 0 key is pressed, twenty characters, at the most, are read from 
the remote port, put into an array called data, and displayed on the screen. 

LAYER: 1 

STATE: read Jin e 

CONDITIONS: ENTER_STATE ( 

ACTIONS: 

{ 

dlsplay_prompt(“ Press L to get next line. ”); 

rmt_lock(); 

) 

CONDITIONS: KEYBOARD “IL" 

ACTIONS: 

{ 

int number; 

unsigned char data [25] ; 
number - rmt_getl(data, 20); 

display f(“\n%u characters read;\n%.20s\n” , number, data); 

) 

rmt_gets 

Synopsis 

extern int rmi_gets (string _ptr, length, wait); 
char * string_ptr; 
int length ; 
int wait; 

Description 

Similar to rmt _getl, this routine gets a specified number of characters from the 
remote port and puts them in an array. Unlike rmt _ge(l, characters continue to 
be read even if a carriage return or linefeed is encountered. The array is not 
NULL-terminated. ( 
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In puts 

The first parameter is a pointer to the array into which the characters will be 

put. 

The second parameter is the number of characters to be read. 

If the specified number of characters is not available from the input queue when 

rmt_getl is called, the third parameter determines when the routine will return: 

• Specify a timeout value in the hexadecimal range °o°i through f f f e (decimal 1 
through 65534) to indicate how long the routine should wait for the specified 
number of characters to become available before returning. During this 
waiting period, no other conditions and actions within the same state will be 
executed. 

At the end of the timeout, the routine returns with less than the specified 
number of characters if all are not available. Timeout values represent 
tenths of a second. If another task has already requested data from the 
queue, this request will be queued. 

• When the value is hexadecimal f f f f , the routine does not return until the 
specified number of characters becomes available. If another task has 
already requested data from the queue, this request will be queued. 

• When the value is zero, the routine returns with less than the specified 
number of characters if all are not available. If there is already an 
outstanding request from another task, a zero value also causes the 
remote-communications process to return from the routine without checking 
the input queue. 

NOTE: More than one test (task) may request data from the 
input queue. The remote-communications processes queues these 
requests as they are made. To ensure that requests are processed 
in turn, use this "wait" parameter consistently across tests. If you 
set the parameter to a non-zero value in a call to rmt _gets (or 
rmt jgetc) in one test, do the same in all tests. 


Balmns 

This routine returns the number of characters read from the remote port. 
Example 

When the [U key is pressed, the INTERVIEW has a minute to read up to 4000 
characters from the remote port, The program puts the characters into an array 
called data, displays them on the screen (until a NULL is encountered— see %s 
in tracef routine, Section 64), and writes them to a file named echojime. This 
is the program that might be run to receive the file transmitted in the rmt_putb 
example. 
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{ 

tf define FILE_LENGTH 4000 

tt define FILENAME "FDl/usr/echo_llme” 

tt Include <stdlo.h> 

tf include <trace_buf.h> 

extern struct tracejbuf iljtrbuf; 

FILE * stream _ptr; 
sizej n; 

unsigned char data ( F1LE_LENGTH ]; 
int count; 

} 

LAYER: 1 

STATE: oet_strlno 

CONDITIONS: ENTER_STATE 
ACTIONS: 

< 

rmt_lock(); 

if((stream _ptr = fopen (FILENAME, “w")) == 0) 
display _prompt(" Cannot open file.”); 
else 
{ 

display _prompl(" Press S to read siring."); 
pos_cursor(l ,0); 

) 

) 

CONDITIONS: KEYBOARD “sS’ 

ACTIONS: ( 

{ 

count = rmt_gets(data, FILE ^LENGTH, 600); 
if (count /= FILE_LENGTH) 

displayfC Could not read entire string. \n”); 
tracef(&ll Jrbuf, “%d characters read: \n%s\n\n", count, data); 
n = fwrite(data, 1, F1LE LENGTH, stream _ptr); 
if(n I = F/LE_LENGTH) 

dispIayf("A write error has occurred. \n"); 
else 

displayfC’Ftle written. \n"); 
if(fclose(stream _ptr) I- 0) 

dlsplayf(" Either file is already closed, or close cannot be executed. \n”); 
else 

display} (“ File closed. \n"); 


rmt_flushi 

Saappsis 

extern int rmt _flushi(); 


If characters have been received in the input queue, but have not been read yet, 
this routine causes them to be discarded. Whenever the INTERVIEW enters or 
leaves Run mode, rmt Jlushi is automatically executed. This ensures that the 
input queue is empty. 
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NOTE: A call to any of the routines which set the parameters of 
the remote port also causes rmt Jlushi to be executed 
automatically. The routines which only get the current 
parameters of the remote port have no effect on the input queue. 

When the programmer calls rmt _flushi, requests for data from the input queue 
are processed before the input queue is flushed. When a call to rmt _flushi is 
made from another test, however, input routines waiting for characters from the 
input queue are returned. 

Returns 

rmt Jlushi returns a zero when the input queue is flushed successfully. 

Otherwise, it returns a non-zero value. 

Example 

This example is the same as that for rmt_getc. Notice that as the program 
enters the first state, the input queue is flushed. 

LAYER: 1 

STATE: getnextcharacter 
CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

display j>rompt(“ Press C to get next character. ”)/ 

rmt Jock (); 
rm t Jlushi (); 

) 

CONDITIONS: KEYBOARD “cC" 

ACTIONS: 

{ 

Int character; 
character = rmt_getc(0 ); 
if (character =--l) 

display _prompl(" No character available. ")! 

else 

display/ '(“ %c" , character); 

) 

rmtjock 

Synopsis 

extern void rmt Jock () ; 

Description 

Recall that in its default state, the input queue does not retain characters 
received through the remote port between requests from user tasks. Data in the 
queue must either be passed to a user task or be discarded. The rmtjock 
routine "locks” all received characters in the input queue until they are 
requested. (Refer again to the beginning of this section.) 
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Example 

The following example is the same as the one for the rmt_getl routine. Notice 
that a call to rmtjock is made as the program begins. The operator makes a 
request for data from the input queue by pressing 0. The next line of data in 
the input queue is removed and put in the array named data . 

LAYER: 1 

STATE: readjlne 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ _ 

display _prompl(" Press L to get next line. "); 

rmtjockf); 

) 

CONDITIONS: KEYBOARD “IL" 

ACTIONS: 

{ 

int number; 

unsigned char data ( 25 ]; 
number - rmt _getl(data, 20); 

display/ ("\n%u characters read:\n%.20s\n", number, data); 

} 

( 

Synopsis 

extern void rmt^unlockf); 

Description 

The rmt_unlock routine implements the inverse of the rmtjock routine. If 
characters are received in the remote port and there are no outstanding requests 
for data, the remote-communications process discards the characters. (Refer 
also to rmtjock and to the beginning of this section.) 

rmtjunlock is automatically executed when the INTERVIEW returns to Program 
mode. 

Example 

In the following example, the input queue is locked as soon as the program 
begins. It remains locked until the operator press 0 (or h°»H ). 

LAYER: 1 

STATE: readjlne 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

display ^prompt ("Press L to get next line, 
rmtjock (); 

) 



rmt unlock 
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CONDITIONS: KEYBOARD *IL' 

ACTIONS: 

{ 

int number; 

unsigned char data (25]; 
number - rmt _getl (data, 20); 

displayf("\n%u characters read;\n%.20s\n", number, data); 

) 

CONDITIONS: KEYBOARD “uU - 
ACTIONS: 

{ 

rmt_unlock(); 

) 

(B) Output Routines 

Use the following routines to transmit data through the remote port. 

rmtputc 

Synopsis 

extern tnt rmt _putc(character, wait); 
unsigned char character; 
int wail; 

D e scri ptio n 

This routine sends a specified character to the output queue of the remote port 
for transmission. 

Inputs 

The first parameter is the character to be transmitted. It may be given as a 
hexadecimal, octal, or decimal constant; as an alphanumeric constant inside 
single quotes; or as a variable. A hexadecimal value must be preceded by the 
prefix Ox or OX; an octal value must be preceded by the prefix 0. If no prefix 
appears before the input, the number is assumed to be decimal. 

If space in the output queue is not available for the character when rmt _putc is 
called, the second parameter determines when the routine will return: 

• Specify a timeout value in the hexadecimal range Vi through f f f e (decimal 1 
through 65534) to indicate how long the routine should wait for space in the 
output queue to become available before returning. During this waiting 
period, no other conditions and actions within the same state will be 
executed. 

If the character is successfully put in the queue, the routine returns zero. 
Timeout values represent tenths of a second. If there is already a request 
from another task, this request will be queued. 
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( 


• When the value is hexadecimal f f f f, the routine does not return until space 
in the output queue becomes available. If there is already a request from 
another task, this request will be queued, 

• When the value is zero and space in the output queue is not available, the 
routine returns -f. The character will not be in the queue. If another task 
is already waiting for access to the output queue, a zero value also causes 
the remote-communications process to return from the routine without 
checking for available space in the output queue. 


NOTE: More than one test (task) may request to send data to 
the output queue. The remote-communications processes queues 
these requests as they are made. To ensure that requests to 
output data are processed in turn, use this “wait” parameter 
consistently across tests. If you set the parameter to a non-zero 
value in a call to rmt jwtc ( rmt _puts or rmt _putb) in one test, do 
the same in all tests. 

Egtums 

If the character is successfully written to the output queue, the routine returns 
zero. If no space is available in the output queue and the routine's “wait" 
parameter is zero or the timeout expires, a -1 is returned. When the parameter 
is zero, a -1 also is returned if another task is already waiting for access to the 
output queue. 

Example 

In the following example, the next character in a fox message is sent to the 
output queue of the remote port each time the operator presses 0. As a 
character is successfully queued, it is displayed in the Display Window. If no 
space is available in the output queue for the character, -1 is returned and a 
message to that effect is displayed on the prompt line. No more characters will 
be sent. 

< 

unsigned char data [) = "{(FOX'S) St 
unsigned char character; 
int i, length, error; 

} 

LAVER: 1 

STATE: transmlt_characters 
CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

display _prompt(" Press C to transmit character 
length = sizeof(data) - 1; 

} 
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CONDITIONS: KEYBOARD “CC” 

ACTIONS: 

. { 

for(l = 0; i < length; /++) 

{ 

character - datajij; 

error = rmt _pulc(character, 0); 

if(error == ~lj 

display_prompt(“No space available In output queue. "); 

else 

display/ ("%c” , character); 

} 

} 

rmt_puts 

Synopsis 

extern int rmt _puts(string_ptr, wall); 

const char * string_plr; 

Int wait; 

Description 

This routine outputs a NULL-terminated string to the output queue of the 

remote port. 

Inputs 

The first parameter is a pointer to the string to be transmitted, 

If space in the output queue is not available for the string when rmt _puts is 

called, the second parameter determines when the routine will return: 

• Specify a timeout value in the hexadecimal range °o°i through f f f e (decimal 1 
through 65534) to indicate how long the routine should wait for space in the 
output queue to become available before returning. During this waiting 
period, no other conditions and actions within the same state will be 
executed. 

Before the timeout expires, as many characters as will fit are put into the 
output queue. Timeout values represent tenths of a second. If there is 
already a request from another task, this request will be queued. 

• When the value is hexadecimal f f f f, the routine does not return until space 
in the output queue becomes available. If there is already a request from 
another task, this request will be queued. 

• When the value is zero and space is not available in the output queue, the 
routine returns the number of characters, if any, put into the queue. If 
another task is already waiting for access to the output queue, a zero value 
also causes the remote-communications process to return from the routine 
without checking for available space in the output queue. 
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NOTE: More than one test (task) may request to send data to 
the output queue. The remote-communications processes queues 
these requests as they are made. To ensure that requests to 
output data are processed in turn, use this “wait" parameter 
consistently across tests. If you set the parameter to a non-zero 
value in a call to rmt _puts ( rmt jmtc or rml jputb) in one test, do 
the same in all tests. 

Returns 

This routine returns the number of characters put into the output queue. 

Eyamefe 

The following example is similar to the one given for rmt _putc. When the (U 
key is pressed, the fox message is sent to the remote port. The difference is 
that the message is output to the remote port as a string (rather than character 
by character). If the output queue is full, the routine does not wait for space to 
become available before returning. The number of characters successfully 
queued is displayed in the Display Window. If the number of characters queued 
is less than the length of the string, a message to that effect is displayed on the 
prompt line. 

< 

unsigned char data l] = “(.(.FOX)) S 
Ini count, length; 

) 

LAYER: 1 

STATE: transmit string 

CONDITIONS:" ENTER_STATE 
ACTIONS: 

< 

display _prompl(" Press S to transmit string. "); 

length = sizeof(data) - 1; 

) 

CONDITIONS: KEYBOARD “eS* 

ACTIONS: 

{ 

count = rmt _puts(data, 0); 
lf(count /^length) 

display _prompt(“ Could not output entire string. "); 

pos_cursor(l , 0) ; 

displayf(“%d characters transmitted.", count); 

} 

rmt_putb 

Synopsis 

extern int rmt _pulb(string_ptr, length, wait); 
const char * string_ptr; 

Int length; 
int wait; 
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Description 

This routine sends a string of specified length to the output queue of the remote 
port. 

Inputs 

The first parameter indicates the string to be output. 

The second parameter is the length of the string to be output. 

If space in the output queue is not available for the string when rmt jputb is 
called, the third. parameter determines. when the routine will return: 

• Specify a timeout value in the hexadecimal range °o°i through f f f e (decimal 1 
through 65534) to indicate how long the routine should wait for space in the 
output queue to become available before returning. During this waiting 
period, no olher conditions and actions within the same state will be 
executed. 

Before the timeout expires, as many characters as will fit are put into the 
output queue. Timeout values represent tenths of a second. If there is 
already a request from another task, this request will be queued. 

• When the value is hexadecimal f f f f, the routine does not return until space 
in the output queue becomes available and all characters in the string have 
been queued. If there is already a request from another task, this request 
will be queued. 

• When the value is zero and space is not available in the output queue, the 
routine returns the number of characters, if any, put into the queue. If 
there is already an outstanding request from another task, a zero value also 
causes the remote-communications process to return from the routine 
without checking for available space in the output queue. 

NOTE: More than one test (task) may request to send data to 
the output queue. The remote-communications processes queues 
these requests as they are made. To ensure that requests to 
output data are processed in turn, use this “wait" parameter 
consistently across tests. If you set the parameter to a non-zero 
value in a call to rmt _putb ( rmt __putc or rmt _puts) in one test, do 
the same in all tests. 

Returns 

This routine returns the number of characters put into the output queue. 
Example 

This is the program that might be run to transmit the file received in the 
rmt _jets example. The user specifies the filename and its size (shown in the 
directory listing on the File Maintenance screen) in the two ttdefine preprocessor 
directives at the beginning of the program. When the program begins, the 
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contents of the file named echo_time are read into an array called data. When 
the operator presses the 0 key, the contents of the array are transmitted and 
displayed. 

< 

it define FILE_LENG TH 4000 

Udefine FILENAME "FD1 /usrlecho_time" 

# include <stdio.h> 

It Include <trace_buf.h> 
extern struct trace Jbuf lljrbuf; 

FILE * stream _ptr; 
size_t n; 

unsigned char data [FILE_LENGTHj; 
unsigned char size [F1LE_LENGTH+100); 

Int count; 

) 

LAYER: 1 

STATE: transmlt_strlng 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

If ((stream j>tr = /open (FILENAME, “r"j ) == 0) 
display _prompt(" Cannot open file."); 
else 
{ 

pos_cursor(l ,0); 

n - fread(data, 1, FILE_LENGTH, stream _ptr); 
lf(n /= FILE LENGTH) 

displayf(“ Either a read error has occurred, or an EOF has been 
encountered. \n"); 
if ([close (stream _ptr) /= 0) 

displayfC Either file Is already closed , or dose cannot be executed. \n“); 

else 

dlsplayfC'Flle closed. \n"); 
if(n == FILE_LENGTH) 

display j)rompt(" Press T to transmit characters."); 

) 

) 

CONDITIONS: KEYBOARD “IT" 

ACTIONS: 

{ 

count - rmt _putb(data , FILE ^LENGTH, Oxff); 
if (count 1= FILEJLENGTH) 

displayfC'Could not output entire string. \n”); 
sprintfisize, "%d characters transmitted: %%.%dH", count, count); 
tracef(&ll_trbuf, size, data); 
tracef(&tl trbuf, “\n\n”) ; 

} 


rmt_flusho 

Synopsis 

extern int rmt Jlushof); 
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Description 

If characters are queued to be output from the remote port, but have not been 
transmitted yet, this routine causes them to be discarded. This ensures that 
anything previously in the output queue port is deleted. 

rmt _flusho is automatically executed when the INTERVIEW returns to Program 
mode. 


NOTE: A call to any of the routines which set the parameters of 
the remote port causes rmt_flusho to be executed automatically. 
The routines which only get the current parameters of the remote 
port have no effect on the output queue. 


Returns 

rmt Jlusho returns a zero when the output queue is flushed successfully. 
Otherwise, it returns a non-zero value. 

Example 

This example is the same as that for rmt _putc. Notice that as the program 
enters the first state, the output queue is flushed. 

{ 

unsigned char data /j = “((FOX)) 
unsigned char character' 
int i, length, error; 

) 

LAYER: 1 

STATE: transmlt_a_character 
CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

rmt JlushoQ; 

display jrompt(" Press C to transmit character. 
length ~ sizeof(dala); 

} 

CONDITIONS: KEYBOARD ‘cC’ 

ACTIONS: 

< 

for(i = 0; i < length; /++) 

{ 

character - datajij; 

error = rmt _putc(character, 0); 

if (error ---I) 

< 

display _prompt(" No space available In output queue. "); 

break; 

} 

else 

dlsplayfC %c" , character); 

) 
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rmt_suspendo 

Synopsis 

extern int rmtjsuspendof ); 


Description 

If characters are queued to be output from the remote port, but have not been 
transmitted yet, this routine causes transmitting to be suspended. The output 
queue is not flushed- Use this routine, only when, the remote port handshaking 
mode is full-duplex without flow control. 

Returns 

rmt_suspendo returns a zero when transmitting is successfully suspended. 
Otherwise, it returns a non-zero value. 

Example 

When the INTERVIEW receives an X-OFF as a signal to stop sending data, it 
suspends transmissions from the remote port. 

{ 

extern event rmt Jnput _not _empty; 
int character ; 

) 

LAYER: 1 

STATE; suspendj>utput 

CONDITIONS? ENTER_STATE 
ACTIONS: 

{ 

rmtlock (); 

) 

CONDITIONS: 

{ 

rmt input notjempty 

) 

ACTIONS: 

{ 

character - rmt_getc(l); 
if (character == 0x13 ) 
rmt_suspendo(); 

} 

TIMEOUT ck Jnput RESTART 0.001 
CONDITIONS: TIMEOUT ckjnput 
ACTIONS; 

< 

character = rmt_getc(l); 
if (character -= 0x13) 
rmt_suspendo() ; 

} 

TIMEOUT ckjnput RESTART 0.001 
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rmt_resumeo 

Synopsis 

extern Int rmt_resumeo( ); 

Description 

This routine resumes transmission of characters from the remote port. Use this 
routine only when the remote port handshaking mode is full-duplex without flow 
control. 

Ret urns 

rmtj'esumeo returns a zero when transmitting is successfully resumed. 

Otherwise, it returns a non-zero value. 

Example 

When the INTERVIEW receives an X-ON as a signal to send data, it resumes 
transmissions from the remote port. 

{ 

int character; 

1 

LAYER: 1 

STATE: resume_output 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

rmt_lock(); 

) 

TIMEOUT RESTART ckjnput 0.001 
CONDITIONS: TIMEOUT check Jnput 
ACTIONS: 

{ 

character = rmt_getc(l); 

If (character == 0x1 1) 
rmt_resumeo(); 

) 

TIMEOUT ckjnput RESTART 0.001 

rmt_send_break 

Scepsis 

extern int rmt_send_break(wait); 
int wait; 

Description 

This routine causes a break, queued as other transmits, to be transmitted. 
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( 


Inputs 

If space in the output queue is not available for the break when rmt_send_break 
is called, the only parameter determines when the routine will return: 

• Specify a timeout value in the hexadecimal range °o°i through F r F t (decimal 1 
through 65534) to indicate how long the routine should wait for space in the 
output queue to become available before returning. During this waiting 
period, no other conditions and actions within the same state will be executed. 

If the break is successfully put in the queue, the routine returns zero. 

Timeout values represent tenths of a second. If there is already a request 
from another task, this request will be queued. 

• When the value is hexadecimal f f f f, the routine does not return until space 
in the output queue becomes available and the break has been queued. If 
there is already a request from another task, this request will be queued. 

• When the value is zero and space in the output queue is not available, the 
routine returns -1. The break will not be in the queue. If another task is 
already waiting for access to the output queue, a zero value also causes the 
remote-communications process to return from the routine without checking 
for available space in the output queue. 

NOTE: More than one test (task) may request to send data to 
the output queue. The remote-communications processes queues 
these requests as they are made. To ensure that requests to 
output data are processed in turn, use this "wait” parameter 
consistently across tests. If you set the parameter to a non-zero 
value in a call to rmt_send_break ( rmt __putc, rmt _puts or 
rmt _putb) in one test, do the same in all tests. 

Returns 

If the break is successfully written to the output queue, the routine returns zero. 

If no space is available in the output queue and the routine’s "wait" parameter 
is zero or the timeout expires, a -1 is returned. When the parameter is zero, a 
-1 also is returned if another task is already waiting for access to the output 
queue. 

Example 

In this example, a break is transmitted each time the operator presses the space 
bar. 

LAYER: 1 

STATE: transmlt_break 

CONDITIONS: KEYBOARD “ ' 

ACTIONS: 

I 

rmt send break(I); 

> 


70-20 


JUL ’90 



70 Remote Port IIP 


(C) Configuration Routines 

The default configuration for the remote port at boot-up is the following: 

Baud rate = 1200 
Bits/character = 8 
Parity = None 
Mode = Full-duplex 

Use the first four routines discussed below to change these settings. The 
programmer’s reconfiguration of the remote port is not affected when the 
INTERVIEW exits or re-enters Run mode, 

A call to any of these set routines causes rmt Jlushi and rmt Jlusho to be 
executed automatically before the parameter is set. 

Use the remaining four routines to read the current parameter-settings for the 
remote port. These get routines have no effect on the input and output queues. 


rmt_set_baud_rate 

Synopsis 

extern int rmt _set_baud_rate (speed); 

Int speed; 

Description 

This routine sets the baud rate for the remote port. The default value at 
boot-up is 1200. 


NOTE: A call to rmt_set_baud_rate causes rmt Jlushi and 
rmt Jlusho to be executed automatically before the baud rate is 
set. 


Inputs 

The only parameter is the desired baud rate. Values that are multiples of 300 in 
the range 300 through 19200 are valid. 

Returns 

If the specified baud rate is valid and successfully set, zero is returned. If the 
baud rate is valid, but not successfully set, -1 is returned. For an invalid baud 
rate, the routine returns -2. 
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Example 

In order for two devices to communicate with each other, they must be using the 
same baud rate. When they are not the same, some devices send a break as a 
signal for the other to adjust its baud rate. If the following example, the 
INTERVIEW changes the baud rate for the remote port whenever a break is 
received. 

{ 

extern event rmt^break; 

int error; 

int speed = 300; 

) 

LAYER: 1 

STATE: ad]ust_baud_rate 
CONDITIONS: 

rmt_break 

) 

ACTIONS: 

{ 

error = rmt_set_baud_rate(speed); 

If (error 1= -l) 

{ 

speed *= 2; 

If (speed > 19200) 
speed = 300; 

} 

else 

dlsplayfC Unable to set the baud rate to %d.", speed); 

) 


rmt_set_bits 

Synopsis 

extern int rmtjsetjbits (value); 
int value; 


Description 

This routine sets the number of bits per character for the remote port. The 
default setting at boot-up is 8 bits/character. 

NOTE: A call to rmt_set_bits causes rmt J'lushi and rmt Jlusho 
to be executed automatically before the number of bits/character 
is set. 


Inputs 

The only parameter is the number of bits/character. Valid values are five 
through eight. 
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Returns 

If the specified number of bits/character is valid and successfully set, zero is 
returned. If the number is valid, but not successfully set, -1 is returned. For 
an invalid value, the routine returns -2. 

Example 

In this example, the number of bits/character for the remote port is set to 7 and 
displayed on the Display Window screen. 

LAYER: 1 

STATE: set_parameter$ 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

displayf("Bits = %d ", rml set i>ils(7)); 

} 

rmt_set_parity 

Synopsis 

extern int rmt_set _parlty (parity); 
int parity; 

Description 

This routine sets the parity for the remote port. The default setting at boot-up 
is no parity. 

NOTE: A call to rmtjset _parity causes rmt Jlushi and 
rmtjlusho to be executed automatically before the parity for the 
remote port is set. 


Inputs 

The only parameter is a value designating the desired parity. Valid values are 
the following: none (0), odd (1), even (2), mark (3), or space (4). 

Returns 

If the specified parity value is valid and successfully set, zero is returned. If the 
value is valid, but not successfully set, -1 is returned. For an invalid parity 
value, the routine returns -2. 
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Example 

In this example, the number of bits/character for the remote port is set to 7 and 
parity is even. Both settings are displayed on the Display Window screen. 
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LAYER: 1 

STATE: set_parameters 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

display/ ("Bits = %d Parity = %d ”, rmt_set_blts(7), rmt_sel _parity(2)); 

) 

rmt_set_mode 

Synopsis 

extern int rmtjsetmode(mode); 

Int mode; 

De& cri ptiofl 

This routine sets the handshaking mode for the remote port. The default setting 
at boot-up is FDX with no flow control. 

NOTE: A call to rmt_sel_mode causes rmt _Jlushi and rmt _flusho 
to be executed automatically before the mode for the remote port 
is set. 


Inputs 

The only parameter is a value designating the mode. Valid values are the 
following: 

0 = Full-duplex with no flow control (FDX) 

1 = Half-duplex (HDX) 

2 = Full-duplex with X-ON/X-OFF characters for flow control 

3 = Full-duplex with DTR and CTS EIA leads for flow control. Use a 

special null-modem cable for direct connections. See Figure 70-1. 
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Figure 70-1 Null-modem cable connections. 


70-24 


JUL ’90 





70 Remote Port I/O 


Rfii um s 

If the specified mode value is valid and successfully set, zero is returned. If the 
value is valid, but not successfully set, -1 is returned. For an invalid mode 
value, the routine returns -2. 

Example 

In this example, the number of bits/character for the remote port is set to 7, 
parity is even, and the mode is set for FDX with X-ON/X-OFF. All three 
settings are displayed on the Display Window screen. 

LAYER: 1 

STATE: setparameters 

CONDITIONS: ENTER_STATE 
ACTIONS: 

< 

display/ ("Biis = %d Parity = %d Mode =%</”, rmt_set_bits(7) , 
rmt set _parity(2), rmt_set_mode(2)); 

) 


rmt_g etba udrate 

Synopsis 

extern ini rmt _gei_baud rate (); 

Description 

This routine gets the current baud-rate setting for the remote port. 

R et urn s 

The baud rate for the remote port is returned. 

Example 

As the program begins, the current baud-rate setting for the remote port is 
displayed on the Display Window screen. 


LAYER: 1 

STATE: baud_rate , 

CONDITIONS; ENTER_STATE 
ACTIONS: 

< 

display/ (“Baud = %d ", rmt_get_baud_rate()); 

) 
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rmt_get_bits 

Synopsis 

extern int rmt_get_b!ts(); 

Description 

This routine tells how many bits there are per character. Possible values are five 
through eight. 

Returns 

The current number of bits per character for the remote port is returned. 
Example 

In this example, the current baud-rate setting and the number of bits/character 
for the remote port are displayed on the Display Window screen. 

LAYER: 1 

STATE: current _parameters 
CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

display /(“ Baud = %d Bits = %d ", rml_get_baud_rate( ), rmt_get_blts()); 


rmt_get_parity 

Synopsis 

extern int rmt^et _parity(); 

Description 

This routine gets the current parity setting for the remote port. 

Returns 

The current number of bits per character for the remote port is returned. 
Example 

In this example, the current baud-rate setting, number of bits/character, and the 
parity for the remote port are displayed on the Display Window screen. 

LAYER: 1 

STATE: current_parameters 
CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

display/ (“Baud = %d Bits - %d Parity = %d ", rmt _get_baud_rate() , 
rmtjset_bits(), rmt_gel _parity()); 

) 
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rmt_getjnode 

Synopsis 

extern int rmt_get_mode(); 

Description 

This routine gets the current handshaking mode for the remote port. 

Returns 

The current handshaking mode for the remote port is returned: 

0 = Full-duplex with no flow control (FDX) 

1 = Half-duplex (HDX) 

2 = Full-duplex with X-ON/X-OFF characters for flow control 

3 = Full-duplex with DTR and CTS EIA leads for flow control Requires 

a special null-modem cable for INTERVIEW-to-INTERVIEW direct 
connections. Refer to Figure 70-1. 


Example 

In this example, the current baud-rate setting, number of bits/character, parity, 
and handshaking mode for the remote port are displayed on the Display Window 
screen. 

LAYER: 1 

STATE: current_parameters 
CONDITIONS: ENTER STATE 
ACTIONS: 

{ 

displayf("Baud = %d Bits = %d Parity - %d Mode - %d ”, rmt_get_baud_rate {), 
rmt_get_bits(), rmt_get _parily(), rmt_get_mode()); 

) 
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Figure 71-1 Sample AUX poll lead configurations for two INTERVIEWS connected by their AUX 
Interfaces. Assume one-way data transmission (i.e., one device is controlling the other). 
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71 AUX Port I/O 


The Auxiliary (AUX) port is a “spare” interface through which the programmer may 
communicate with other lab equipment. The AUX port is located at the rear of the 
INTERVIEW, between the printer and RGB connectors. It is controlled by a Zilog CIO 
(Counter/Timer, Parallel /nput/Output Unit) chip. The AUX port may be used as a serial or 
parallel interface. When it is operated as a parallel port, up to sixteen bits (one bit on each 
of sixteen leads) may be transmitted simultaneously. 

AUX-port control must be coded in C regions on the Protocol Spreadsheet. There are no 
spreadsheet-token equivalents of the C variables and routines described in this section. 

A normal configuration of equipment using the AUX port will involve two INTERVIEWS with 
AUX port setups that mirror each other to some extent, as in Figure 71-1. The transmitting 
( INTERVIEW will use one of its output leads as a “strobe" to signal to the receiving 

INTERVIEW that an AUX word is available to be read. The receiver will detect this strobe 
as an aux_change event. 

The receiving INTERVIEW will use one of its output leads to acknowledge each AUX word 
received. The transmitting INTERVIEW will detect this acknowledgment as an aux_change 
event. 


NOTE: The AUX port is not controlled by the same CPU that 
handles the user program. The need for interprocessor 
communication without data buffering makes rapid, successive 
transmissions difficult to handle. It is recommended, therefore, 
that control bits be set aside for flow control— a bit set by the 
transmitter as input/control is set by the receiver as 
output/non-control, and vice versa— and that every output word 
be acknowledged before a succeeding word is output. 


71.1 Variables 

Table 71-1 lists the variables specific to AUX I/O operations. The fast-event 
variable, aux_change, detects a change in a lead that has been configured as a 
control lead. Any or all of the sixteen leads in the interface may be designated 
control leads. Section 71.2 explains how to configure control leads. 
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t 


aux_change does not establish which control lead(s) has changed. Two associated 
variables, curr_aux_yalue and prev_aux_value, indicate the status of all sixteen leads. 
These are two-byte (short) variables. Each lead is represented by a different bit in 
the short. If the bit-value of a given lead is zero, the lead is on. If the bit-value is 
one, the lead is off. 

Whenever a control lead changes, the value in curr_aux_value is written to 
prevjiux_yalue. Then curr_aux_value is updated. 


Table 71 -t 

AUX Port I/O Variables 


Type 

Variable 

Meaning 

extern fast_event 

aux_change 

True when the 9tatus of a lead 
designated as control (and 
Input) changes. Is automatically 
made to come true by the CIO 
chip as soon as leads have been 
configured via set^auxjdlrectlon 
and set_aux_ctl_leads routines, 
Therefore, condition must be 
tested again In a different state. 
Line Setup configured for 
emulate or monitor mode. 

extern volatile const unsigned short 

curr_aux_value 

Each bit designates a different 
lead. A bit-value of one 
Indicates a given lead Is on. 
When value of curr_aux_value Is 
exclusive ored (') with 
prev_auxj/alue , result Indicates 
those leads whose status has 
changed. Updated when 
aux_change come9 true. Line 
Setup configured for emulate or 
monitor mode. 

extern volatile const unsigned short 

prev_aux_value 

Value of previous 
curr_aux_value. Updated when 
control leads change, but only 
after logic has had a chance to 
compare current and previous 
leads. Line Setup configured 
for emulate or monitor mode. 
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71.2 Routines 

In the examples for the following routines, assume that two INTERVIEW’S are 
connected and that data flows in one direction. 


CAUTION: You may damage the AUX interface if the same lead 
is designated as output on both units. We suggest that you set 
the leads on each unit as input/output and control/non-control 
before you connect the AUX interfaces. See Figure 71-1. 


set_aux_direction 

Synopsis 

extern void set_aux_direction(input_or_output); 
unsigned short input_or_output; 


Description 

This routine designates leads on the AUX port as input or output. Designated output 
leads for the transmitter are set as input leads by the receiver. 

Inputs 

The only input is a sixteen-bit variable. Each bit in the variable designates one lead 
and may be set to zero (output) or one (input). 


Example 


Both sides of the connection may be transmitter or receiver. But for simplification in 
examples, let’s designate only one side as the transmitter and the other as the 
receiver. In this example, the transmitter sets all 8 bits of the low-order byte as 
output bits for data, the low-order bit of the high byte as input (for handshaking), 
the next 6 bits of the high byte as input (unused), and the high-order bit as output 
(the receiver will designate this bit as input for handshaking). 

LAYER: 1 

STATE: setjnputjeads 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

set aux_dtrection(0x7f00); 

) 
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The other (receiver) INTERVIEW sets a bit as input (for handshaking). It must be 
one that was designated as output by the transmitter, the highest-order bit of the high 
byte. The data bits set as output by the transmitter must be set as input by the 
receiver. The receiver’s set _aux -direction routine would look like this: 

LAYER: 1 

STATE: set Input Jeads 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

set jnux -direction ( Oxfeff ) ; 

) 


set_aux_ctl_leads 

Synopsis 

extern void set _aux_ctl Jeads (ctljor_not); 
unsigned short ctl_orjtot; 


Description 

This routine determines whether or not leads will be control leads. Control leads 
must also be input leads, but input leads do not necessarily have to be control leads. 
Output leads can never be control leads. 


Inputs 

The only input is a sixteen-bit variable. Each bit in the variable designates one lead 
and may be set to zero (non-control) or one (control). 


Example 


Assuming the input/output bits set in the previous example, the transmitter sets all 8 
data bits (output) as non-control, the low-order input bit of the high byte as control 
(for handshaking), the next 6 input bits of the high byte as non-control (unused), 
and the high-order output bit as non-control (the receiver will designate this bit as 
control for handshaking). 

LAYER: 1 

STATE: set_control Jeads 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

set-OUX—CtlJea ds(0x0100); 

> 
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The “receiver" INTERVIEW sets one input bit as control for handshaking purposes. 
It must be one that was designated as output by the transmitter, the highest-order bit 
of the high byte. The receiver’s set_aux_ctl_leads routine would look like this: 

LAVER: 1 

STATE: set_controMeads 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

set_aux_ctl leads(0x8000); 

) 


wrlte_aux 

Synopsis 

extern void write_aux(output_word ); 
unsigned short output_word; 


Description 

This routine sends a combination of data, control, and (perhaps) unused bits as 
output. Input bits are not transmitted by the CIO. 


Inputs 

The only input is a sixteen-bit variable. Each bit designates one lead and may 
represent data or control information, or be unused, If a given lead was designated 
as a control lead, it is an input lead and the CIO will not transmit the status of the 
bit in any case, so its setting of 1 or 0 does not matter. If the lead was designated as 
a non-control lead, it might contain data, be unused, or contain an alternating value 
to indicate acknowledgment (if the other side designated it as a control lead). 


Example 

The transmitting INTERVIEW is going to send data to the receiving INTERVIEW. 
Before the next transmission can be sent, an acknowledgment must be received. The 
acknowledgment is detected by the fast-event variable aux_change. 


NOTE: The CIO chip automatically generates a true aux_change 
condition when the s et_aux_ctl_leads routine has been executed. 
The aux_change condition, therefore, should be placed in a 
separate programming state from the set_aux_ctljeads routine. 
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The transmitter’s program might look like this: 

LAYER: 1 

{ 

extern fastjevent aux_change; 

extern volatile const unsigned short curr_aux_value ; 

volatile unsigned short curr; 

unsigned short mask; 

unsigned char data ; 

) 

STATE: configure leads 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

setjsux_d\rection (0x7/00); 
setauxjctlleads (0x0100); 
curr = curr_aux_value; 
data - 0x01; 
mask = curr “ 0x8000; 

display jprompt(“ Connect cable. Press spacebar to transmit. 
pos_cursor(J ,0); 

} 

NEXTSTATE: sendjiata 
STATE: eendjfata 

CONDITIONS: KEYBOARD * " 

ACTIONS: 

l 

if (data <= 10) 

{ 

write aux(mask \ data); 

dlsplayf(“Transmlssion %d waiting for ACK, \n" 

) 

) 

NEXT_STATE: waiting 
STATE: waiting 

CONDITIONS: {aux change) 

ACTIONS: 

{ 

dala++; 

mask = (mask " 0x8000); 

displayf("ACK received : %04x Press spacebar to transmit. \n”, 

) 

NEXT_STATE: send_data 
CONDITIONS: { data > 10} 

ACTIONS: 

< 

display _prompt(“ End of test. 

) 


, data); 


curr); 
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The receiver’s program would look like this: 

LAYER: 1 

{ 

extern fast_event auxjshange; 

extern volatile const unsigned short c urr_aux_value; 

volatile unsigned short curr; 

unsigned short mask; 

int count; 

) 

STATE: conflgurejeads 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

set_aux_direction (Oxfeff); 
set_aux ell leads (0x8000 ) ; 

} 

CONDITIONS: { aux_change ) 

ACTIONS: 

{ 

curr = curr_aux_vaiue; 
count = 1; 

mask = curr “ 0x0100; 

display _prompt(" Connect cable. Ready to receive. "); 

pos_cursor(J ,0); 

} 

NEXT_STATE: recelve_data 
STATE: recelve_data 

CONDITIONS: { aux change } 

ACTIONS: 

{ 

displayff'Transmission %d received: %04x Press spacebar to send ACK. \n", 

count, curr); 

} 

NEXT_STATE: send_ack 
CONDITIONS: { count > 10) 

ACTIONS: 

{ 

display _prompt(“ End of test. 

) 

STATE: send^ack 

CONDITIONS: KEYBOARD “ ■ 

ACTIONS: 

{ 

if (count <= 10) 

{ 

write_aux(mask); 

count**; 

mask = (mask “ 0x0100); 

) 

) 

NEXT_STATE: recelve_data 
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NOTE: If you designate more than one lead as control, you 
might need to compare prev_aux_value with curr_aux_value to 
determine if the lead you are interested in is the one that 
changed. Here, since there is only one input-control lead on 
each side, the event auxjchange is sufficient to signal and to 
acknowledge transmission. The value of prev_aux_value does not 
have to be checked. 


set_aux_reg 

Synopsis 

extern void set_aux_reg(reg_value_word); 
unsigned short reg_vatue_word; i 

Description 

The CIO chip may be reconfigured by the user via the set_aux_reg routine. 


NOTE: At present, the initial configuration of the Master 
Interrupt Control Register is (0x0082). The initial configuration 
of the Master Configuration Control Register is (0x0194). 


Inputs 

The only input is a sixteen-bit variable. The high byte is the CIO register number; 
the low byte is the value to store in the register number. For register numbers and 
their values, consult Appendix B in Zilog’s Z8036 Z-CIO/Z8536 CIO Counter/Timer 
and Parallel I/O Unit Technical Manual, March 1982. 

Example 

The Master Configuration Control Register allows for selective enabling/disabling of 
the CIO ports. Port A's input/output is reflected in the least-significant byte of 
reg_value_word. Port B’s input/output is reflected in the most-significant byte of 
reg_value_word. 


NOTE: Port C of the CIO chip is used internally and Is not 
available to the user of the INTERVIEW. 
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Suppose you want to disable port B input, output, and interrupts (ports A and C 
enabled) in one state, and in another state restore the original configuration (ports A, 
B, and C enabled): 

LAYER: 1 

STATE: reconflgure_chlp 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

set_aux_reg(0x01 ]4); 

) 

STATE: restore orfglnahconflg 
CONDITIONS: ENTER_STATE 
ACTIONS: 

sel_aux_reg(0x01 94 ) ; 

) 
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72 Other Library Tools 

The C structures, variables, and routines in this section provide additional programming tools 
not specific to any particular protocol. Most of these tools approximate layer-independent 
conditions or actions. Refer to Section 30 for more detailed explanations of the purposes of 
specific conditions and actions. Sometimes the name of the variable or routine is sufficient 
for identifying its related spreadsheet token. When this is not the case, the information is 
provided below. 


72.1 Structures 

Use the structures tm, crnt_tm, and prevjm listed in Table 72-1 to monitor the 
current and previous date and time. Each minute the values in crntjlm are copied 
to prevjm. Then crntjm is updated. These structures are used to produce the 
date/time displays at the top of Run-mode screens and the Date/Time Setup screen. 

The variables flag_struct.prev, flagjstruct. current, and flagjstruct. old (in the 
flagjtruct structure) are used each time a flag is incremented, decremented, or set 
to a particular value. The current, previous, and old values these variables represent 
work the same way as their counterparts in the counter structure, discussed fully in 
Section 65.1(A). 


NOTE; The purpose of flags is to make it easy for the user to 
isolate selected bits in a variable. The translator does most of the 
work of flags by taking. the user’s flag masks and coding them in 
C. Flags constructed entirely in C bypass the translator and 
require the programmer to create the Tag-mask code normally 
generated by the translator. 


Before using the timeout routines included in this section, declare an instance of the 
timeout structure shown in Table 72-1. Refer to the timeout _restart_action and 
timeout jtopjaction routines for examples of how to use this structure. 

The keyboard structure stores the value of the most recent ASCII key used. The 
structure variable keyboard. value is updated only by the fast-event variable 
keyboard _new_key. 
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Table 72-1 

Structure Fields— Other Library Tools 

Type Variable Value (hex/decimal) Meaning 



Declared as type extern struct. Declared 
automatically If program KEYBOARD condition Is 
used. Updated by keyboard_new_key event 
variable. Reference the structure variable as 
follows: keyboard. value. 

ASCII value of key Just executed. 


Int 

tm_seo 

Int 

tmmln 

Int 

tmjiour 

Int 

tnrwnday 

Int 

tm_mon 

Int 

tm_year 

Int 

tm_wday 

Int 

tm_yday 

Int 

tmjsdst 



Structure of time of day. Declared as type 
extern struct. Reference a structure variable as 
follows: tm.tm_sec. 

0-30/0-59 

Seconds after the minute. Not currently 
updated: always set to -1. 

0-30/0- 59 

Minutes after the hour. 

0-17/0-23 

Hours since midnight. 

1-1111-31 

Day of month. 

O-b/O-1 1 

Months since January. 
Years since 1900. 

0-6 

Days slnoe Sunday. Not currently updated; 
always set to -1 . 

0-1 6d 10-365 

Days since January 1. Not ourrently updated; 
always set to -1 . 

Daylight Savings Time flag. Not currently 
updated; always set to -1 . 


Structure of current time of day. Updated every 
minute. Declared as type extern struct tm. 


Structure of previous time of day, one minute 
ago. Declared as type extern struct tm. 


flag_$truct 


unsigned short prev 

unsigned short current 

unsigned short old 


Structure of a flag. Declared as type struct. 
Declared automatically if a program flag Is used. 
Program flags assigned to structure as follows: 
strucf flagjstruct (fagjiame. Reference a 
structure variable as follows: llagjname. current. 

When converting a flag action to C, the translator 
compares prev with current to determine 
whether flag has changed. Then prev is updated 
to current and flagjname_change Is signaled. 

This value of flag Is acted on directly by program 
actions. 

When converting a flag condition to C, the 
translator compares old with current to 
determine whether true condition Is new 
(transitional!. After program logic has examined 
flag, old Is updated to prev. 
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Table 72-1 (continued) 


Type 

Variable 

Value (hex/decimal) Meaning 

Structure Name: timeout 

Structure of a timeout. Declared as type struct. 
Declared automatically If a program timeout Is 
used. Program timeouts assigned to structure 
as follows: struct timeout name. Reference a 
structure variable as follows: 
f/meouf_name.evenf_/d. 

unsigned long 

eventjd 

Four bytes of a 6-byte timeout, containing the 
segment number and offset. 

Timeout _name_sfop routines set this event Id to 
zero. 

unsigned short 

event_!d_uld 

Two bytes of a 6-byte timeout which uniquely 
Identify (uld) the timeout. Do not try to assign a 
value to this variable. 

72.2 

Variables 



All of the variables in Table 72-2 are valid in either emulate or monitor mode. 


(A) Monitoring Events 

The event variables in Table 72-2 are fevarjtime_of_day, flag_name_change, 
timeout _name_expired, signaljtame, keyboard _new_key, and 
keyboard _new_anyjcey. 

Event variable fevarjime_of_day comes true once a minute. An example of 
how to use this variable is provided in Section 57.1. This event variable is part 
of the spreadsheet TIME condition. 

The event variable keyboard _new _key is used by the translator in a spreadsheet 
KEYBOARD condition. It comes true when any ASCII key is pressed. The event 
keyboard jxew _any _key , on the other hand, comes true when an ASCII or other 
keyboard key is pressed. The only keys which will not trigger this event are (^], 
[ffSH . and 

(B) Status Variables 

Status variables are those in Table 72-2 that do not include event in the Type 
column. Their associated event variables guarantee that they are updated and 
tested. 

Time and date variables are updated by fevar_titne_of_day. Variables 
crnt_time_of_day, prev_time_of_day, crnt daie _ofjday , and prev_date_of_day 
are older versions of variables that belong to the crnt_tm and prev_tm structures. 
The C translator uses these older versions when it construct time-of-day 
conditions (e.g., CONDITIONS: TIME 1614). 

The status variable keyboard _any _key is updated by the fast-event variable 
keyboard _new_any_key. 
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Table 72-2 

Other Library Variables 


Type Variable Value (hex/decimal) Meaning 


extern fast event 


extern event 


extern event 


extern event 


extern volatile unsigned short 


extern volatile unsigned short 


extern volatile const unsigned char 


extern volatile const unsigned char 


extern fast event 


fevarjlme_of_day 


flag_name_change 


tlmeout_name_explred 


slgnal_name 


crnt_tlme_of_day 


prev_tlme_of_day 


crnt_date_of_day 


prev_date_of_day 


keyboard_new_key 


True once per minute. Line 
Setup configured for emulate or 
monitor mode. 

This event must be signaled by 
the program Itself; it Is not 
“external” to the program. The 
translator signals this event as 
part of the FLAG Increment, 
decrement, or set action. Line 
Setup configured for emulate or 
monitor mode. 

This event must be signaled by 
the program Itself. It Is not 
“external" to the C program. 
The translator signals this event 
as part of the 

timeout j-estart_actlon routine . 
Line Setup configured for 
emulate or monitor mode. 

True when the named signal Is 
the argument In a signal routine. 
Spreadsheet-token equivalent Is 
ON_SIGNAL name. Line Setup 
conTlgured for emulate or 
monitor mode. 

0-937/0-2359 Current time Is stored In this 
variable. Updated as soon as 
time changes. Line Setup 
configured for emulate or 
monitor mode. 

0- 937/0-2359 Current time Is stored In this 

variable. Updated when time 
changes, but only after logic 
has had a chance to compare 
current and previous time. Line 
Setup configured for emulate or 
monitor mode. 

1- 1//1-31 Current date Is stored In this 

variable. Updated as soon as 
date changes. Line Setup 
configured for emulate or 
monitor mode. 

1-1/11-31 Current date Is stored In this 
variable. Updated when date 
changes, but only after logic 
has had a chance to compare 
current and previous date. Line 
Setup configured for emulate or 
monitor mode. 

True when any ASCII key Is 
pressed. Line Setup configured 
for emulate or monitor mode. 
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Table 72-2 (continued) 


Type 


Variable Value (hex/decimal) Meaning 


extern fast_event 


extern volatile unsigned short 


keyboard_new_any_key 


keyboard_any_key 


0-7110-127 

80-17// 

128-383 

180/384 
181/385 
182/386 
183/387 
184/388 
185/389 
186/390 
187/391 
18a/394 
IBb/395 
180/396 
18d/397 
180/398 
18f/399 
190/400 
191/401 
192/402 
193/403 
194/404 
195/405 
196/406 
197/407 
198/408 
199/409 
19a/410 
19b/41 1 
19C/412 
19d/413 
190/414 
10d/269 
1a0/416 
1 a 1 /4 1 7 


True when any key Is pressed. 
The only exceptions are 0 . 

and |0. Line Setup 
configured for emulate or 
monitor mode. 

Identifies last key or 
key-combination executed. Line 
Setup configured for emulate or 
monitor mode. 

ASCII keys 

not used 
Field entry keys: 

0 

G1D 

0 

(Ml 

0} 

|ptn[ - |amil 

|cr*.| ~ |q.EAfil 

0 

0-0 

0-0 

0-0 

0- [i£LI 

0-IM1 

0-(M3 

0-0 

0-ft88li) 

0 - El 

0-0 

0-0 

m 

m 

(ZU 

(F4) 

(ED 

ED 

Ezl 

(ED 

0-01 


(keyboard_any_key variable continued on next page ) 
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Table 72-2 (continued) 


Type 


Variable Value (hex/decimal) Meaning 


(keyboard _any_key continued) Editing Keypad Keys ( cont ) : 


1a2/418 

583 

1a3/419 

@ 

1a4/420 


1a5/421 

fssi 

1a6/422 

0-G£3 

1a7/423 

0-GlSD 

1a8/424 


1a9/425 


laa/426 

B-00 

lab/427 

B-daD 

lac/428 

B-H39 

lad/429 

0-fS5il 

Utility Keys: 

1 bO/432 


lbl/433 

s 

1b2/434 


1b3/435 

@ 

1b4/436 


1b5/437 


1b7/439 

B) 

1b8/440 

s 

lba/442 

□ 

lbb/443 

0-D 

lbc/444 

B-0 

lbd/445 


1 be/446 


lbf/447 

jtwn]_|ftvw) 

1 CO/448 

|crx]-| *VU 1 

lcl/449 

|>KfT)-flOfcb| 

1C2/450 

|cm|-|LrW)| 

1C3/451 

B-B 

1C4/452 

B-B 

1C5/453 

0-B§ 

1 C6/454 

|cw.|-[fwgi1 

1C7/455 

(B-FE3 

lcB/456 

B-fB 

1o9/457 

B-B 

lca/458 

B-B 

lcb/459 

[mn|-|wmr| 

Icc/460 

|cm|-| w| 

lcd/461 

B-B 

Ice/462 

B-B 


(keyboard_any_key variable continued on next page) 
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Table 72-2 (continued) 


Type 


( 


Variable Value (hex/decimal) Meaning 


( keyboard_any_key continued) 

1d0/464 

ldl/465 

1d2/466 

1d3/467 

1d4/468 

1d5/469 

1d6/470 

1d7/471 

1d8/472 

1d9/473 

Ida/474 

ldb/475 

ldc/476 

ldd/477 

lde/478 

190/480 
let/481 
1e2/482 
1e3/483 
1e4/484 
105/485 
1e6/486 
107/487 
108/488 
1e9/489 
lea/490 
leb/491 
lec/492 
led/493 
loe/494 
let/495 
lfO/496 
lfl/497 
1(2/498 
1 f 3/499 
1 f 4/500 


Pure Cursor Keys (cont): 

0 

M-B 

(™)-0 

0 

@-0 

B-B 

0 

|mn] - |*mij 

B-M 

0 

M-B 

B-B 

0 

M-B 

B-0 

Cursor Keypad Keys: 


BE) 

S 



M-B 

[Ml 


(Ml 

Gap 

ran 

B-M 
B-B 
M- 1C&1 
B- IB&l 
M-fWI 
B-l M I 
M-fWl 
B-fMl 
M-fM! 
B- IK5I 
M-r^i 
B- l Sift 1 


(keyboard _any_key variable continued on next page) 
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Table 72-2 (continued) 


Type Variable Value (hex/decimal) Meaning 


( keyboard _any_key continued) Other Keys: 

1(5/501 [™]-(D 

1(6/502 

1(7/503 @-(D 

1(8/504 |^) -B 

1(9/505 B-d) 

1 (a/506 @-(D 

1(b/507 

1(0/508 fcT^|-(i) 

188/392 ®-(D 

189/393 

1 (d/509 [™]-B 


72.3 Routines 


timeout_restart_actlon 

Synopsis 

extern void timeout _restart_actlon(tlmeout_name _ptr, value, function); 
struct * timeout name _ptr 
{ 

unsigned long event Jd; 
unsigned short event_id_uid; 

); 

unsigned short value; 
void function (); 

Description 

This routine starts a named timeout timer running down, starting at a specified value. 
When the timer reaches zero, a named function is called, The 

timeout _restart_action routine, preceded by a call to the timeout _stop_action routine, 
is the equivalent of the softkey TIMEOUT name RESTART action on the Protocol 
Spreadsheet. 


Inputs 

The first parameter is a pointer to the timeout structure. See Table 72-1 for further 
explanation of the timeout structure. 

The second parameter is the starting value of the timeout timer in milliseconds. 
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The third parameter is the name of a routine to be called when the timeout expires. 
The routine may include the following statement: timeout jiame. event Jd = 0;. 
Timeout-stop actions set this event ID to zero. This action is not strictly necessary 
here, since the timeout has already expired; but the action may make the processing 
of subsequent stop actions slightly more efficient. 

The body of the routine to be called may also include this statement: 
signal(timeout_mme_expired);. In a softkey-entered TIMEOUT RESTART action, both 
statements are included in a routine called timeout_name_isp. 


NOTE: The routine named in the third parameter is an interrupt 
service process (isp) . A long definition for this routine makes the 
processing of timeout _restart_action unpredictable. 


Example 

When a frame is sent, start a timeout timer at 2 seconds. When it expires, sound 
the alarm. If another frame is sent before the 2 seconds expires, stop the current 
timer and restart the timeout. 

{ 

struct timeout 

{ 

unsigned long event_id; 
unsigned short evenl_id_uid; 

); 

struct timeout timeout ^example; 
extern event tlmeout_example_expired; 
void timeout _example_isp () 

{ 

timeout _example. event _id = 0; 
signal (tlm eout_example_expired); 

) 

) 

LAVER: 2 

STATE: example_oMlmeout 
CONDITIONS:" FRAME_SENT 
ACTIONS: 

{ 

timeout _stop_action(&timeout_example); 

timeout _restart action (&timeout example, 2000, tlmeout_example_lsp); 

) 

CONDITIONS: 

{ 

timeout_example_expired 

) 

ACTIONS: ALARM 

Here is a version of the program that accomplishes the same result without an action 
to signal the timeout event: 
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struct timeout 

{ 

unsigned long event Jd; 
unsigned short event_id_u!d; 

>; 

struct timeout timeoutjexample; 
extern void sound_alarm(); 

) 

LAYER: 2 

STATE: example_of_tlmeout 
CONDITIONS:"” FRAME_SENT 
ACTIONS: 

{ 

tlm eouts top_actlon ( &tlm eout_exampl e ) ; 

timeout jrestart_action(&timeout example, 2000, sound_alarm); 

} 

timeout_stop_action 

Synopsis 

extern void tlmeout_stop_action(limeoutjiame _ptr); 
struct * timeout _name _ptr 
< 

unsigned long event_id; 
unsigned short event Jd uid; 

}; 


Description 

This routine stops a named timeout timer, preventing it from expiring. The softkey 
equivalent of this routine is the TIMEOUT name STOP action on the Protocol 
Spreadsheet, timeout _stop_action also precedes the call to the timeout_restartjiction 
in the spreadsheet TIMEOUT name RESTART action. 

Inputs 

The only parameter is a pointer to the timeout structure. See Table 72-1 for further 
explanation of the timeout structure. 

Example 

In this example, if the user presses the GD key, the timeout timer will not expire and 
the alarm will not sound (until another frame is sent and the timeout is restarted). 

{ 

struct timeout 

< 

unsigned tong event Jd; 
unsigned short event id uid; 

); 

struct timeout timeoutjexample; 
extern void sound_alarm(); 

} 
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LAYER: 2 

STATE: stop_a_tlmeout 

CONDITIONS: FRAME^SENT 
ACTIONS: 

{ 

timeout _stop_actlon (ddimeout _example) ; 

timeout restart _actlon(&timeout example, 2000, sound jalarm); 

} 

CONDITIONS: KEYBOARD “Ss” 

ACTIONS: 

{ 

timeout_stop_aclion(&timeout_example ); 

} 


index 

Synopsis 

extern char * lndex(strlng, character); 
char * string; 
char character; 

PeSCfiptipn 

This routine searches for an instance of a character starting at the beginning of a 
specified list. The routine is used by the C translator to convert CONDITIONS: 
keyboard softkey entries into C. This routine must be declared. 

Inputs 

The first parameter is a list of characters to be searched. 

The second parameter is the character to be searched for in the list. 

Returns 

This routine returns a pointer to the first instance of the specified character, or zero 
if it does not occur. 

Example 

In the example below, the following test is established: when a key is pressed on the 
keyboard, search for a match to the keyboard character in the string “ abc ". If it is 
found, sound the alarm. 

{ 

extern char * indexQ; 

extern fastjevent keyboard _new_key; 

extern struct keyboard 

i 

char value; 

); 

extern Struct keyboard keyboard; 

) 
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LAYER: 1 

STATE: lndex_example 
CONDITIONS: 

{ 

(keyboard _new_key <4<fc lndex(" abc ”, keyboard. value!) 

) 

ACTIONS: ALARM 

Let’s suppose that the user presses the space bar. In this case, the returned pointer 
will be pointing to the blank preceding the "a.’’ If rindex had been used, the 
returned pointer would be pointing to the blank following the “c,” As long as any 
non-null character is returned, the condition is true. 

rindex 

Synopsis 

extern char * rindex(string, character); 
char * string; 
char character; 

Description 

This routine searches for an instance of a character starting at the end of a specified 
list. This routine must be declared. 

Inputs 

See index. 

Returns 
See index. 

Examp le 
See index. 


load_program 

Synopsis 

extern void load _program(filename _ptr) 
const char * filename _ptr; 

Deseriptign 

The load _program routines allows you to link programs together while the unit is in 
Run mode. When a call to load program is encountered in a spreadsheet program, 
the current program is exited. The program named as the argument in the routine is ( 


72-12 


JUL '90 




72 Other Library Tools 


loaded and run. When you return to Program mode, the program displayed on the 
Protocol Spreadsheet will be the one just loaded. If load _program fails, you are 
returned to the main menu screen in Program mode. 

Inputs 

The only input is the absolute pathname, prefixed by the device name, of the file to 
be loaded. Valid device names are "HRD,” "FD1,” and “FD2." 

Example 

In the example below, at the successful conclusion of the last of a series of tests in 
module 18, a program for module 19 will be loaded and run. 

LAYER: 3 

STATE: test_26 

CONDITIONS: ENTER_STATE 
ACTIONS: SEND DIAG 
CONDITIONS: RCV CLEAR CONF 
ACTIONS: TRACE “Test_26 passed' 

< 

load _pro£ram(“FDl/usr/modute~19"); 

) 


lock 

S yno psis 

# include <stdlo.h> 

extern void lock(lock_variable_ptr) ; 

int * lockjvariabie _ptr; 

D es cri pti on 

The lock routine implements a lock using the integer variable pointed to by the 
routine parameter. If the lock variable is currently locked, the task goes to sleep. 
When an unlock on the same variable occurs (within an independent task), the task 
invoking the lock function will attempt to claim the lock. If successful, the task is 
executed; otherwise, it goes back to sleep until the next unlock. 


NOTE: If locking is used at any place in the program, all related 
or possibly concurrent routines must also use the locking 
functions. 


NOTE: The lock variable should always be defined as a global 
integer, never as local to a function. The lock variable should 
never be altered by the user program or deadlock can occur. 
Deadlock also results if the lock is invoked twice within the same 
task without an intervening unlock. 
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Inputs 

The only parameter is a pointer to the lock variable. 


Exa m ple 

Two tasks concurrently write to their own file streams. (The file streams are local to 
the routine write _fox, making them independent of each other even though they have 
the same name.) However, during the / close operation (which automatically calls 
/flush), both tasks need to write to the same file. The locking routines ensure that 
the writes to the file occur sequentially, not concurrently. 

{ 

tttnclude <stdio.h> 

const char data () = "{(.FOX')) \n"; 

int key; 

void write ^ fox() 

{ 

FILE * stream _ptr; 
sizej n; 
lock(&key ); 

ifUstream _ptr = fopen("FD2lusrlbu//01", “a”)) -- 0) 

display _prompt(“ Cannot open file. "); 

else 

display _prompt(" File opened. "); 

n = fwrite(data, 1, sizeof(dala)-l , stream _ptr); 
pos_cursor(1 ,0); 
if(n 1= (sizeof(data)-l)) 

displayf(“Write error. \n"U 

else 

displayf("Write completed. \n”) ; 

If (/close (stream _ptr) != 0) 

display/ (“Either file is already closed, or close cannot be executed. "); 

else 

display/ (“File closed. "): 

unlock(ikey); 

} 

) 

LAYER: 1 

TEST: a 

STATE: wrlte_and_slgnal 

CONDITIONS: RECEIVE STRING “THE QUICK BROWN FOX” 

ACTIONS: SIGNAL xyz 

1 

write JoxQ; 

) 

TEST: b 

STATE: wrlte_only 

CONDITIONS: ON_SIGNAL xyz 
ACTIONS: 

{ 

write _fox()\ 

} 
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unlock 

Synopsis 
# Include <sldlo.h> 

extern void unlock(lock_variable _ptr); 
int * lock_variabte _ptr; 

Description 

The unlock routine implements the inverse of the lock routine using the same integer 
variable. Sleeping tasks will be woken up to retry their attempt to claim the lock. 
One will succeed, and the rest will go back to sleep. See also lock routine. 

Inputs 

The only parameter is a pointer to the lock variable. 

Ex a m p le 

See lock routine. 

signal 

Synopsis 

extern void signal (signat_name ) ; 

Description 

This routine conveys instructions to other tests and layers where conditions are 
monitoring the signal by name. The softkey equivalent of this routine is the SIGNAL 
action on the Protocol Spreadsheet. 

Inputs 

The only parameter is a name descriptive of the event being signaled. 

Example 
LAVER: 2 

STATE: slgnal_routlne 

CONDITIONS: RCV FRMR 
ACTIONS: 

{ 

signal(signal_link_down); 

) 

CONDITIONS: ON_SIGNAL llnk_down 
ACTIONS: ALARM 

Here is a related example, this time with the signal detection also given in C. Note 
that a signal automatically generates an ‘'event” that can be detected alone in a 
waitfor clause. 
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{ 

extern event llnk_down; 

) 

LAYER: 2 

STATE: slgnal_event 

CONDITIONS: RCV FRMR 
ACTIONS: 

{ 

signal (llnk_down) ; 

} 

CONDITIONS: 

{ 

llnk_down 

) 

ACTIONS: ALARM 


sound_a!arm 

Synopsis 

extern void sound _alarm (); 

Description 

This routine will sound the alarm. The softkey equivalent of this routine is the ( 

ALARM action on the Protocol Spreadsheet. 

Example 

When a bad BCC is detected on the DTE side of the link, sound the alarm. 

LAYER: 1 

STATE: example 

CONDITIONS: DTE BAD_BCC 
ACTIONS: 

{ 

sound_alarm (); 

) 


start_rcrd_play 

Synopsis 

extern void start_rcrd _play(); 

Description 

Depending on the Line Setup configuration, this routine activates data recording or 


playback. If the Line Setup menu shows Mode: monitor , source: 

routine controls playback. In all other cases, it initiates recording. 


bisk , the 


72-16 


JUL '90 




72 Other Library Tools 


Unless your recording source is RAM. make a call to f close in programs containing 
disk I/O routines (Section 68) before you start to record (or resume playback). If 
you don’t, the file will be closed automatically as soon as recording (or playback) 
begins, even if processes on the file have not been completed. (Using the key to 
activate recording or resume playback will have the same effect.) 

Example 

LAYER: 1 

STATE: example 

CONDITIONS: KEYBOARD “ ’ 

ACTIONS: 

{ 

start_rcrd _play(); 

) 

suspend_rcrd_play 

Synopsis 

extern void suspend rcrd j>lay(); 

Description 

Depending on the Line Setup configuration, this routine suspends data recording or 
playback. If the Line Setup menu shows Mode: MONITOR $1, Source: oisk, the 

routine controls playback. In all other cases, it suspends recording. Once recording 
or playback is suspended, resume it with a call to startrcrd __play. 

Unless your recording source is RAM, do not call disk I/O routines (Section 68) until 
you suspend recording (or playback). If you do, the disk I/O operation will fail. 

NOTE: Although playback is immediately suspended when 
suspend jrcrd _play is executed, the screen display continues until 
the character buffer's contents are fully displayed. (For 
bit-image data, the FIFO must empty.) At slower playback 
speeds, you may notice a slight delay before the display actually 
freezes. 


Example 

LAYER: 2 

STATE; example 

CONDITIONS: KEYBOARD * ’ 
ACTIONS: 

{ 

suspend _rcrd _play() ; 

) 
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send_key 

Synopsis 

extern void send_key (number _of Jceys , keys _ptr); 
unsigned char numberjofjceys; 
unsigned short * keys _ptr; 

DgjgriptiPD 

This routine sends a specific keystroke (or sequence of keys) during Run mode, as 
though the operator pressed the key. It also may be used to change the Run-mode 
display. 


Inputs 

The first parameter specifies the number of keys to be sent. 

The second parameter is a pointer to an array of shorts. This array lists the keys to 
be sent. To send keyboard keys, use the values listed in Table 72-2 for the 
keyboard _any_key variable. To change the Run-mode display, send two keys. The 
first "key" always has a value of 0xff75. The second “key” identifies the desired 
display-screen. Use the values listed in Table 64-1 for the crnt_display_screen 
variable. 


Example 

For this example, assume you are playing back data from a disk and that the initial 
Run-mode screen is the dual-line data display. After a five-second pause, playback 
is slowed as though you pressed 0. As soon as a bad BCC is detected on the DTE 
side, the data display will change to the Layer 2 Protocol Trace screen. 


{ 

unsigned short keys j] = {Oxf/75, 0x42); 
unsigned short siowjdown [) = {Oxide); 

} 

LAYER: 2 

STATE: changa_dlsplays 

CONDITIONS: ENTER STATE 
ACTIONS: TIMEOUT pause RESTART 5 
CONDITIONS: TIMEOUT pause 
{ 

send_key(l, slow down); 

) 

CONDITIONS: DTE BDBCC 
ACTIONS: 

{ 

send_key(2, keys); 

) 
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surrender_cpu 

Synopsis 

extern void surrender _cpu(); 

Description 

This routine surrenders the CPU, placing the calling task onto the end of the ready 
queue. If no other tasks are currently ready to run, this routine returns. 

Use surrenderjcpu only when executing C code which started as part of an 
ENTER_STATE condition. It is useful in programs containing a task that only performs 
computations (i.e., no I/O operations like disk accesses). Make a call to 
surrender _cpu to give other tasks on the same CPU a chance to run. 

Example 

In the following example, one task on a CPU waits on a rcvd Jrame event variable in 
order to count frame types. For each of the different frame types, another task 
displays the value of the counter. Without a call to surrenderjcpu, the display task 
would monopolize the CPU, preventing the frame-counting task from running. 

{ 

extern event rcvd Jrame; 

extern volatile const unsigned char rcvd jramejype; 
unsigned short frame _type_count [256]; 
void display Jramejype count() 

{ 

pos_cursor(7, 12); 

displayf("%3u", frame _type_count/0]; 
pos_cursor(7,22); 

dlsplayf("%3u“, frame jype_count[l); 

t* ... Continue to position and display count for each frame type */ 


} 

} 

LAYER: 2 

TEST : d!splay_frame_types 
STATE: only 

CONDITIONS: ENTER_STATE 
ACTIONS: 

{ 

pos_cursor(3,23); 

displaysC FRAME COUNTS BY TYPE"); 
pos_cursor(5,ll); 

disptays("INFO RR RNR REJ ...); 
whlle(l) 

{ 

display Jrame Jypejcount (); 
surrender_cpu(); 

) 

} 
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TEST: count frame types 
STATE: only 
CONDITIONS: 

{ 

revd Jrame 

) 

ACTIONS: 

{ 

t-y frame _type _count [revd _Jrame_iypej; 

) 
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